Skip to main content
API docs by Redocly

Signicat Authentication REST API (v1)

Download OpenAPI specification:Download

Introduction

The Signicat Authentication REST API enables you to interact with the Signicat eID and Wallet Hub, our digital solution for identity verification and authentication. This API allows you to authenticate users and organisations securely through a wide selection of electronic ID methods (eIDs).

This REST API uses the OAuth 2.0 protocol for authorisation. All request and response bodies are formatted in JSON.

Get started

Before you can start making requests to this API, you need to learn how to connect to it. To do this, see the Connect to Signicat APIs Quick start guide.

Using this API

Audit logs

Use the Signicat Audit logs service to see documented evidence of the sequence of activities that have affected a system.

  • Access it: Signicat Dashboard > Settings > Audit logs
  • For information generic to all Signicat audit logs, see the general Audit logs documentation.

Errors

When you make an API call to Signicat and an error occurs, you will receive a response message with an error code.

  • For errors generic to all Signicat APIs, see the general Error codes documentation.

Events (callback)

Use the Signicat Events service to automatically receive information about when something happens in one of our services into your system.

  • Access it: Go to Signicat Dashboard > Settings > Events
  • For information generic to all Signicat events, see the general Events documentation.

Note: This is often referred to as callback.

Authentication Session

Create a new session

Use this endpoint to create a session. This must contain a JSON object (as described) with all the info needed.

Request Body schema: application/json
required

JSON object with data used necessary for creating the session.

object (PrefilledInput)

The session's prefilled input information (it is required at least one value).

object or null

Additional parameters that modify the authentication flow. Depends on selected IdP. See developer documentation for details.

object (CallbackUrls)

Specifies the different urls to callback to.

object (EncryptionKey)

Encryption key information.

requestedLoa
string or null
Enum: "low" "substantial" "high"

Specifies the LoA (Level of Assurance).

tags
Array of strings or null <= 100 items

A set of support optional tags to group and filter webhooks. The maximum length for each tag is 100.

returnUrl
string or null <uri>

If specified the embedded view will return to this URL after authentication is completed (successfully or not). If not specified, a success or error screen will be shown inside the embedded view.

embeddedParentDomains
Array of strings or null

Specify the parent domains that will embed the authentication. This will be used for content security frame ancestor header if set, as an extra security mechanism to protect against clickjacking.

object (PaymentPrefillData)
allowedProviders
Array of strings or null

A list of Identity Providers (IdPs) that can be used for authentication. If not specified, the end-user will be able to choose from all IdPs associated with your Signicat account. The maximum length for each Provider is 30.

language
string or null

The desired language for the UI. Expected format ISO 639-1. If the requested language is not available, it will automatically default to English (en). Some IdPs may have a different fallback language due to regional considerations.

flow
required
string
Enum: "headless" "redirect" "embedded"

The selected flow used for this specific authentication session. To learn more about using the headless flow with Swedish BankID, please refer to this example. If flow is set to Redirect the field CallbackUrls is required.

themeId
string or null [ 0 .. 10 ] characters

The themeId you want to use for this specific authentication session. If not specified, the default theme for your account will be used.

requestedAttributes
required
Array of strings

The attributes you wish to get back from the authentication of the end-user. To find a list of which attributes can be requested, please see documentation for that specific ID method which can be found on https://developer.signicat.com/identity-methods/.

Defaults to empty.

externalReference
string or null [ 0 .. 100 ] characters

An external reference for you, will be returned as a URL parameter on callbackUrls.

usageReference
string or null

An usage external reference for you to group your billing.

sessionLifetime
integer or null <int32>

Lifetime of session in seconds (Default is 1200 seconds). It has a soft-minimum value of 300 seconds, which means if the value set is less then 300, it will be automatically set to 300 seconds.

requestDomain
string or null

This specifies the domain you want to use for this specific session. The domain will be visible in the end-user's browser. This domain needs to be correctly configured on your account!

Responses

Request samples

Content type
application/json
{
  • "prefilledInput": {
    },
  • "additionalParameters": {
    },
  • "callbackUrls": {},
  • "encryptionPublicKey": {
    },
  • "requestedLoa": "low",
  • "tags": [
    ],
  • "returnUrl": "https://example.com/auth_callback",
  • "embeddedParentDomains": [
    ],
  • "paymentPrefillData": {
    },
  • "allowedProviders": [
    ],
  • "language": "en",
  • "flow": "redirect",
  • "themeId": "agkaa12",
  • "requestedAttributes": [
    ],
  • "externalReference": "my-reference-12345",
  • "usageReference": "my-usage-reference-12345",
  • "sessionLifetime": 600,
  • "requestDomain": "myapp.app.signicat.com"
}

Response samples

Content type
{
  • "id": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "accountId": "a-rand-cnnJOtEwafuhom0nv",
  • "authenticationUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
  • "statusUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
  • "status": "SUCCESS",
  • "statusDetail": "Error because reasons.",
  • "provider": "nbid",
  • "subject": {
    },
  • "callbackUrls": {},
  • "idpData": {
    },
  • "environment": {
    },
  • "error": {},
  • "messageTransportProperties": {
    },
  • "tags": [
    ],
  • "paymentPrefillData": {
    },
  • "loa": "substancial",
  • "risk": {
    },
  • "allowedProviders": [
    ],
  • "language": "en",
  • "flow": "redirect",
  • "themeId": "agkaa12",
  • "requestedAttributes": [
    ],
  • "externalReference": "my-reference-12345",
  • "usageReference": "my-usage-reference-12345",
  • "sessionLifetime": 600,
  • "requestDomain": "myapp.app.signicat.com",
  • "expiresAt": "2024-06-01T13:45:30"
}

Get session status

Use this endpoint to get information regarding a previously created session.

path Parameters
id
required
string

The session identifier.

query Parameters
sessionNonce
string

The sessionNonce used for the embedded flow

userChallengeVerifier
string

The verifier used for the sk-smartid and audkenni-app IDPs

Responses

Response samples

Content type
{
  • "id": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "accountId": "a-rand-cnnJOtEwafuhom0nv",
  • "authenticationUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
  • "statusUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
  • "status": "SUCCESS",
  • "statusDetail": "Error because reasons.",
  • "provider": "nbid",
  • "subject": {
    },
  • "callbackUrls": {},
  • "idpData": {
    },
  • "environment": {
    },
  • "error": {},
  • "messageTransportProperties": {
    },
  • "tags": [
    ],
  • "paymentPrefillData": {
    },
  • "loa": "substancial",
  • "risk": {
    },
  • "allowedProviders": [
    ],
  • "language": "en",
  • "flow": "redirect",
  • "themeId": "agkaa12",
  • "requestedAttributes": [
    ],
  • "externalReference": "my-reference-12345",
  • "usageReference": "my-usage-reference-12345",
  • "sessionLifetime": 600,
  • "requestDomain": "myapp.app.signicat.com",
  • "expiresAt": "2024-06-01T13:45:30"
}

Cancel Authentication Session

path Parameters
id
required
string

The session identifier.

Responses

Response samples

Content type
{
  • "id": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "accountId": "a-rand-cnnJOtEwafuhom0nv",
  • "authenticationUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
  • "statusUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
  • "status": "SUCCESS",
  • "statusDetail": "Error because reasons.",
  • "provider": "nbid",
  • "subject": {
    },
  • "callbackUrls": {},
  • "idpData": {
    },
  • "environment": {
    },
  • "error": {},
  • "messageTransportProperties": {
    },
  • "tags": [
    ],
  • "paymentPrefillData": {
    },
  • "loa": "substancial",
  • "risk": {
    },
  • "allowedProviders": [
    ],
  • "language": "en",
  • "flow": "redirect",
  • "themeId": "agkaa12",
  • "requestedAttributes": [
    ],
  • "externalReference": "my-reference-12345",
  • "usageReference": "my-usage-reference-12345",
  • "sessionLifetime": 600,
  • "requestDomain": "myapp.app.signicat.com",
  • "expiresAt": "2024-06-01T13:45:30"
}