Skip to main content
API docs by Redocly

Signicat Authentication REST API (v1)

Download OpenAPI specification:Download

Signicat's Authentication REST API allows you to interact with the Signicat eID Hub. Our digital solutions enable identity verification and authentication through a wide selection of electronic ID methods. The Authentication REST API is a REST API with all request and response bodies formatted in JSON.

Authorisation

For more information on how to access the Authentication REST API, see the Accessing Signicat API products guide in our developer documentation.

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.

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!

expiresAt
string or null <date-time>

DateTime expiry of session.

Responses

Request samples

Content type
application/json
{
  • "prefilledInput": {
    },
  • "additionalParameters": {
    },
  • "callbackUrls": {},
  • "encryptionPublicKey": {
    },
  • "requestedLoa": "low",
  • "tags": [
    ],
  • "returnUrl": "https://example.com/auth_callback",
  • "embeddedParentDomains": [
    ],
  • "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"
}

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": [
    ],
  • "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.

Responses

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "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": [
    ],
  • "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"
}