Authentication REST API

Table of contents

• User attributes (requestedAttributes)
• Redirect flow
  • Overview of the setup
  • Set up the API client
  • Create a session
  • Get the session status
• Headless flow
  • Overview of the headless setup
  • Set up the API client (headless)
  • Create a session (headless)
  • Get the session status (headless)
  • Cancel a session (optional)
  • How to complete a headless flow

This page details how to set up authentication for Swedish BankID using Signicat's Authentication REST API, either with redirect or headless flow. Requests are sent from your backend server to Signicat's Authentication REST API.

The currently supported mechanisms for authentication with Swedish BankID are:

• QR code: Launches the QR code flow on a remote device.
• App launch: Launches the BankID app locally on the same device.
• Phone flow: Allows authentication via a telephone call.

The mechanisms are set up in the same way, except for some minor differences in field values, as described in the following sections.

General documentation

If you want to read more about the basics of our eID Hub product before you start integrating with Swedish BankID, see the:

• Authentication REST API documentation for a conceptual description of the flows.
• API Reference (opens new window) for endpoint descriptions.

User attributes (requestedAttributes)

You can request the following attributes from users of Swedish BankID. These attributes are common for both the redirect and headless flows:

Name	Example value (in result)	Description
name	Per Testeson	Full name of user
firstName	Per	First name of user
lastName	Testeson	Last name of user
dateOfBirth	1990-10-27	Birth date of user (ISO 8601 format)
nin	{ "value": "199010270537", "issuingCountry": "SE", "type": "PERSON" }	National identity number of user, along with some metadata
sbidDeviceIp	127.0.0.1	IP address of the device where the BankID app was run
sbidXmlSignature	PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi...	Base64 encoded XML signature returned by BankID as proof of authentication
sbidOcspResponse	MIIHdgoBAKCCB28wggdrBgkrBgEFBQcwAQEEggdcMIIHWDCCA...	Base64 encoded OCSP response for end user’s BankID certificate
sbidOcspResponderId	C=SE,O=Testbank A AB (publ),SERIALNUMBER=111111111111,CN=Testbank A Customer CA3 v1 for BankID Test OCSP Signing	Distinguished Name of the OCSP responder (extracted from sbidOcspResponse)

You add them in the requestedAttributes as shown in the request examples further down.

Redirect flow

This section details how to set up authentication for Swedish BankID using the redirect flow. The redirect flow allows you to pass a URL to your end-users which they will open in a browser.

Overview of the setup

This is an overview of what you need to do to set up a redirect flow:

• Set up the API client
• Create a session
• Get the session status

Set up the API client

Before you can make a request to the Authentication REST API, you need to set up an API client to obtain client credentials. You use these client credentials in a request to obtain an access token. How to do this is described in the General information section. The access token needs to be passed in as an HTTP Bearer authentication header when sending the requests.

Create a session

Request

To create a session, send a POST request to https://api.signicat.com/auth/rest/sessions (for reference details, see the Create a new session (opens new window) endpoint description).

Request example: Remote flow (QR)

Here is an example request body for an authentication, using the remote flow (QR code). If the authentication completes successfully, the final result will contain the attributes that were requested.

{
    "allowedProviders": ["sbid"],
    "flow": "redirect",
    "additionalParameters": {
        "sbid_initial_flow": "REMOTE_FLOW",
        "sbid_intention_text": "TG9nIGludG8gbXkgb25saW5lIGJhbmtpbmcgYWNjb3VudA=="
    },
    "prefilledInput": {
        "nin": "1234567890"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    }
}

Upon sending this request, the BankID session will start.

Phone flow

Here is an example request body for an authentication with the Phone flow:

{
    "allowedProviders": ["sbid"],
    "flow": "redirect",
    "additionalParameters": {
        "sbid_auth_type": "PHONE",
        "sbid_phone_initiator": "OPERATOR"
    },
    "prefilledInput": {
        "nin": "1234567890"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    }
}

Field descriptions

To initialise an authentication with BankID, you can use the following fields in the initial request:

Field	Required	Example value	Description
allowedProviders	No	["sbid"]	Specify ["sbid"] if you want to be sent directly to Swedish BankID. Don’t send this field if you want to show a list of all the ID methods your account has connections for.
flow	Yes	redirect	MUST have the value redirect.

See below for a description of additionalParameters and the API Reference (opens new window) for the other fields.

Control the user flow (additionalParameters)

You use additionalParameters to control the redirect flow. This is not a required field.

Name	Values	Description
sbid_initial_flow	DETECT, APP_LAUNCH or REMOTE_FLOW	Controls which authentication flow should be presented first to the user: -DETECT automatically determines if the user is on a mobile or a desktop device, and presents APP_LAUNCH or REMOTE_FLOW respectively. This is the default behaviour. -APP_LAUNCH launches the BankID app locally. -REMOTE_FLOW presents the QR code flow.
sbid_app_redirect	myapp://redirect	Possibility to apply the app redirect URL that you have added to the allowlist on the Dashboard Configuration (opens new window) page.
sbid_auth_type	NORMAL or PHONE	Controls which type of flow is started for Swedish BankID: - NORMALlaunches the regular Authentication flow (can be further specified by sbid_initial_flow) . - PHONE launches the Phone flow. Note: For the Phone flow to work, you must also include sbid_phone_initiator and enable the Phone flow in the Dashboard configuration (opens new window).
sbid_phone_initiator	USERor OPERATOR	Defines the default selected radio button in the first screen of the Phone flow: - USER means the User radio button is selected as default. - OPERATOR means the Operator radio button is selected as default.
sbid_intention_text	TG9nIGludG8gbXkgb25saW5lIGJhbmtpbmcgYWNjb3VudA==	A text specifying the intention of the authentication. Notes: - Must be encoded in UTF8 Base64 format. - Max length of the Base64 encoded string: 1500 characters. For more details, see Define intention text.
sbid_intention_text_format	simpleMarkdownV1	Defines the format of the intention text to simpleMarkdownV1. For more details, see Define intention text

Prefill user information (prefilledInput)

You can use the prefilledInput parameter to prefill information about the user, for example, so the user does not have to fill in this information manually.

Only for `nin`

Prefilling of user information only applies to the national identification number (nin) for Swedish BankID. You cannot prefill other user data.

Name	Required	Example value	Description
nin	No	"prefilledInput": {"nin": "1234567890"}	Prefills the national identity number. If prefilled, only the user with that nin value will be able to authenticate.

Response

Here is an example response after you have created a session:

{
    "id": "58126fb8-c5e2-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=58126fb8-c5e2...",
        "abort": "https://example.com/abort?sessionId=58126fb8-c5e2...",
        "error": "https://example.com/error?sessionId=58126fb8-c5e2..."
    },
    "allowedProviders": [
        "sbid"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ],
    "sessionLifetime": 600
}

What you need to do with the response

You must redirect the end-user to the authenticationUrl found in the response. This is a unique URL which allows the user to perform the Swedish BankID authentication in context of the session you just created.

Get the session status

Request

No data specific for Swedish BankID needs to be provided in this request.

To get the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can find the id value in the response that was returned when you created the session. For more information about the "Get session status" endpoint, see the API Reference (opens new window) description.

Response

The response will contain a status field, which you must use to see what the current status of the session is. Below you can see an example response for a successfully completed session:

{
    "id": "58126fb8-c5e2-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "SUCCESS",
    "provider": "sbid",
    "subject": {
        "id": "opuc4kyFUWPkfdmfYTzjS89u6ZCWLHWLZfPR5hpBW24=",
        "idpId": "199010270537",
        "firstName": "Per",
        "lastName": "Testeson",
        "nin": {
            "value": "199010270537",
            "issuingCountry": "SE",
            "type": "PERSON"
        }
    },
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=58126fb8-c5e2...",
        "abort": "https://example.com/abort?sessionId=58126fb8-c5e2...",
        "error": "https://example.com/error?sessionId=58126fb8-c5e2..."
    },
    "allowedProviders": [
        "sbid"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ],
    "sessionLifetime": 600
}

Status overview

Status	Description
WAITING_FOR_USER	The user has not started to authenticate yet.
SUCCESS	The authentication is successful. Authentication result is present in the response.
ABORT	The session was cancelled by the end-user.
ERROR	The BankID session was not completed in time.

What you need to do with the response

If the returned status is SUCCESS, you will find information about the authenticated user in the subject object.

You will also see what provider was actually used by checking the provider field. This can be useful if you allowed more than one provider when you created the session.

Headless flow

This section details how to set up headless authentication for Swedish BankID. This means that you can provide your own user interface within your app or website.

Overview of the headless setup

This is an overview of what you need to do to set up a headless authentication:

• Set up the API client
• Create a session
• Get the session status
• Cancel a session (optional)
• How to complete a headless flow with QR or app launch

Set up the API client (headless)

Before you can make a request to the Authentication REST API, you need to set up an API client to obtain client credentials. You use these client credentials in a request to obtain an access token. How to do this is described in the General information section. The access token needs to be passed in as an HTTP Bearer authentication header when sending the requests.

Create a session (headless)

Request

You can use the https://api.signicat.com/auth/rest URL and send the request to the /sessions endpoint, including the accountId parameter. The full request URL should look like this:

https://api.signicat.com/auth/rest/sessions?signicat-accountId={accountId}

You can find the accountId in the Signicat Dashboard.

For reference details, see the Create a new session (opens new window) endpoint description.

Request example: QR code flow

Here is an example request body for a headless authentication, using the QR code flow. This example also applies to the App Launch flow (just replace QR with APP_LAUNCH). If the authentication completes successfully, the final result will contain the attributes that were requested.

{
    "allowedProviders": ["sbid"],
    "flow": "headless",
    "additionalParameters": {
        "sbid_flow": "QR",
        "sbid_end_user_ip": "123.123.123.123",
        "sbid_intention_text": "TG9nIGludG8gbXkgb25saW5lIGJhbmtpbmcgYWNjb3VudA=="
    },
    "prefilledInput": {
        "nin": "1234567890"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ]
}

Request example: Phone flow

Here is an example request body for headless authentication, using the Phone flow:

{
    "allowedProviders": ["sbid"],
    "flow": "headless",
    "additionalParameters": {
        "sbid_auth_type": "PHONE",
        "sbid_phone_initiator": "OPERATOR"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "nin",
        "dateOfBirth",
        "sbidAge",
        "sbidOcspResponse",
        "sbidXmlSignature",
        "sbidOcspResponderId",
        "sbidVerificationTime",
        "sbidVerificationSignature"
    ],
    "prefilledInput": {
        "nin": "196809179176"
    }
    
}

Field descriptions

To initialise a headless authentication with BankID, you must specify the following required fields in the initial request:

Field	Required	Example value	Description
allowedProviders	Yes	["sbid"]	MUST have the value ["sbid"].
flow	Yes	headless	MUST have the value headless.

Control the user flow (additionalParameters)

You use additionalParameters to control the headless flow:

Field	Required	Example value	Description
sbid_flow	Yes	QR	Legal values: -QR for the QR code flow - APP_LAUNCH for the BankID app launch flow Note: Regardless of whether QR or APP_LAUNCH is specified here, the API responses will contain the necessary data to conduct an app launch flow. However, to get the necessary data for a QR flow, the value MUST be given as QR.
sbid_auth_type	No	NORMAL or PHONE	Controls which type of flow is started for Swedish BankID: - NORMALlaunches the regular Authentication flow (can be further specified by sbid_flow) . - PHONE launches the Phone flow. Notes: - For the Phone flow to work, you must also include sbid_phone_initiator and enable the Phone flow in the Dashboard configuration (opens new window). - You must send nin as prefilled.
sbid_phone_initiator	No	USERor OPERATOR	Defines the default selected radio button in the first screen of the Phone flow: - USER means the User radio button is selected as default. - OPERATOR means the Operator button is selected as default.
sbid_end_user_ip	Yes	123.123.123.123	IP address representing the user-agent/device of the end-user as seen by your service. This could be gathered from the requests you receive from the end user's user-agent/device. This must be in a valid IPv4 or IPv6 format.
sbid_intention_text	No	TG9nIGludG8gbXkgb25saW5lIGJhbmtpbmcgYWNjb3VudA==	A text specifying the intention of the authentication. Notes: - Must be encoded in UTF8 Base64 format. - Max length of the Base64 encoded string: 1500 characters. For more details, see Define intention text.
sbid_intention_text_format	No	simpleMarkdownV1	Defines the format of the intention text to be simpleMarkdownV1. For more details, see Define intention text.

Prefill user information (prefilledInput)

You can use the prefilledInput parameter to prefill information about the user, for example, so the transaction is locked down to a specific user.

Only for `nin`

Prefilling of user information only applies to the national identification number (nin) for Swedish BankID. You cannot prefill other user data.

Name	Required	Example value	Description
nin	Sometimes	"prefilledInput": {"nin": "1234567890"}	Prefills the national identity number. If prefilled, only the user with that nin value will be able to authenticate. For the PHONE flow this field is required, otherwise it is not required.

Response

Here is an example response for the session creation:

{
    "id": "3d07c219-...",
    ...
    "idpData": {
        "autoStartToken": "db65b172-c9a4-43e3-82bf-0db09d7f922e",
        "qrData": "bankid.c157aec7-e179-424..."
    }
}

Field descriptions

The response to the session creation will contain an idpData field, which in turn contains the necessary data that you need in your frontend.

Field	Example value	Description
autoStartToken	db65b172-c9a4-43e3-82bf-0db09d7f922e	Must be used when building the URL for launching the BankID app on the same device. - iOS: https://app.bankid.com/?autostarttoken=<autoStartToken>&redirect=<urlToYourAppOrWebPage> - Android (modern): https://app.bankid.com/?autostarttoken=<autoStartToken>&redirect=null - Android 4 and 5: bankid:///?autostarttoken=<autoStartToken>&redirect=null
qrData	bankid.c157aec7-e179-424d-bee7-d54c9ece06fa.0.5b6b54c5a8939fa152da2a9689bf 50c14233ada0c79a67a2a52b1f8ba579ff35	Initial data to display in a QR code. The QR code must be updated with the qrData you receive as a result of every request to get the session status. Only available if you started the session with "sbid_flow": "QR"

What you need to do with the response

Based on the type of flow you are using, do the following:

• QR: Display a QR code to the end-user with the idpData.qrData as content. For more details, see the separate QR code flow section below.
• APP_LAUNCH: Display a launch button for triggering the app launch URL. For more details, see the description of autoStartToken in the table above and the separate APP_LAUNCH flow section below.

Errors

HTTP Status Code	Error code	Description
400	idp:sbid:already-in-progress	A request for the given NIN (National Identity Number) is already in progress. Both sessions are cancelled.
400	idp:sbid:invalid-parameter	You have sent an invalid parameter to BankID’s infrastructure, for example an invalid end-user IP address (see sbid_end_user_ip in the additionalParameters table above).
500	idp:sbid:rp-service-error	Failed to create a transaction towards BankID’s infrastructure.
500	idp:server-problem	Internal server error occurred while creating the session.

Get the session status (headless)

Request

No data specific for Swedish BankID needs to be provided in this request.

You send the request to /sessions/{id}?signicat-accountId={accountId}. You can find the id value in the response that was returned when you created the session. You can find the accountId in the Signicat Dashboard. For more information about the "Get session status" endpoint, see the API Reference (opens new window) description.

Response

Content of idpData

The response will contain an idpData field, which contains necessary input data for your frontend.

If you are using the QR flow, you must update your QR code with the data received in the qrData field.

Field	Example value	Description
qrData	bankid.c157aec7-e179-424d-bee7-d54c9ece06fa.0.5b6b54c5a8939fa152da2a9689bf50c14233ada0c79a67a2a52b1f8ba579ff35	Updated data to display in a QR code. Only available if you started the session with "sbid_flow": "QR" and you received status WAITING_FOR_USER.
sbidStatus	OUTSTANDING_TRANSACTION	Can be used to get more detailed status information, which can be used to make decisions. See possible values in the Status table below.

Status

In the response you will get a top level status in the status field. For some of these statuses you will find a more detailed status in idpData.sbidStatus.

Backwards compatibility

To prevent your integration from breaking if we add more statuses to idpData.sbidStatus and error.code, please handle unexpected values as follows:

• Unknown idpData.sbidStatus with top level status WAITING_FOR_USER: Treat as OUTSTANDING_TRANSACTION
• Unknown error.code with top level status ERROR: Treat as an unknown error

Here are some response examples with different statuses (see the Status table below for descriptions of the different statuses):

Example response: WAITING_FOR_USER

{
	"id": "4c88a3e2-b10e-4148-914d-f3f93f1ad76f",
	"status": "WAITING_FOR_USER",
    "idpData": {
        "sbidStatus": "OUTSTANDING_TRANSACTION",
        "qrData": "bankid.c157aec7-e179-424d-bee7-d54c9ece06fa.0.5b...",
    },
    ...
}

Example response: ABORT

{
	"id": "4c88a3e2-b10e-4148-914d-f3f93f1ad76f",
	"status": "ABORT",
    ...
}

Example response: ERROR

{
	"id": "4c88a3e2-b10e-4148-914d-f3f93f1ad76f",
	"status": "ERROR",
    "error": {
        "code": "idp:sbid:timeout",
        ...
    },
    ...
}

Status overview

Status	idpData.sbidStatus	error.code	Description
WAITING_FOR_USER	OUTSTANDING_TRANSACTION		The user has not started to authenticate yet. End-user guidance: Instruct the user on what they need to do (e.g. scan QR code or click a button to launch the app). BankID recommends the RFA13 or RFA1 (opens new window) user messages, but these do not take the QR code into consideration.
	NO_CLIENT		The BankID app has not been started yet. For all practical purposes this can be treated the same way as OUTSTANDING_TRANSACTION.
	STARTED		No BankID found on device yet. This may take a few seconds. BankID recommends you to continue polling if you get this status. For mobile device you can in practice choose to stop polling if you get this status more than a few times in a row. End-user guidance: Instruct the user that they need to wait. BankID recommends the RFA14 or RFA15 (opens new window) user messages. In practice though, it might not make sense to show such long messages which in the majority of cases will only be shown until the next poll.
	USER_SIGN		The user has started to authenticate. End-user guidance: Instruct the user to complete the authentication in their app. BankID recommends RFA9 (opens new window), but this is a bit misleading for fingerprint.
SUCCESS			The authentication is successful. Authentication result is present in the response.
ABORT			The session was cancelled by the end-user.
CANCELLED			The session was cancelled by you or the end-user.
ERROR		idp:sbid:timeout	The BankID session was not completed in time.
		idp:sbid:cert-error	The end-user certificate could not be trusted (invalid security code, revoked or invalid certificate).
		idp:sbid:start-failed	The BankID app was not started within a certain time limit.
		idp:sbid:rp-service-error	An error occurred when contacting the BankID service.
		idp:sbid:cancelled	The session was cancelled since someone started a parallel session for the user (security feature by BankID).
		idp:sbid:unknown-error	Unknown error occurred.

What you need to do with the response

Depending on the top level status you receive in the response, you need to handle the response a bit differently:

• For WAITING_FOR_USER status you want to read the idpData.sbidStatus and handle the response accordingly. See information in the Status table above on what to do.
• For SUCCESS status you will find the authentication result in the subject field.
• For ABORT status you can assume that the end-user intentionally cancelled the transaction.
• For ERROR status you can check the error.code field to see what kind of error occurred.
• For CANCELLEDstatus you or the end-user has cancelled the transaction.

If you get statuses that are not listed here, see Backwards compatibility in the start of this section.

Cancel a session (optional)

You can stop an ongoing authentication session by using the Cancel flow (opens new window) endpoint.

This is useful if you want to:

• Provide a way for your end-users to cancel the transaction, both at Signicat and Swedish BankID (via a link/button). It is especially useful if you lock the transaction to a particular national identity number.
• Cancel an ongoing transaction for a particular national identity number before starting a new transaction for the same person.

A successful cancellation returns 200 OK of type CANCELLED.

Example response

{
  "id": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "accountId": "string",
  "status": "CANCELLED",
  "provider": "sbid",
  ...
}

Errors

HTTP Status Code	error.code	Description
500	idp:server-problem	Internal server error occurred while cancelling the session.

How to complete a headless flow

The following sections describe how you can set up a complete headless flow for QR code and APP_LAUNCH, using the above information.

QR code flow

For the QR code flow, you must display an “animated” QR code to the end-user. Animating the QR code is done by updating the content of the displayed QR code for every status call. This is a mandatory security feature of Swedish BankID.

The process is as follows:

1. Create a new session with sbid_flow set to QR.
2. Take the idpData.qrData from the initial response and display as a QR code to the end-user.
3. Poll for status every 1 to 3 seconds. If you receive top level status WAITING_FOR_USER:
   • If idpData.sbidStatus is OUTSTANDING_TRANSACTION or NO_CLIENT, you must update the displayed QR code with the content of the idpData.qrData returned in the status responses.
   • For other values of idpData.sbidStatus, see the description in the Status table above for information on what to show. Continue polling until the value for status is either SUCCESS, ABORT, or ERROR, at which point the session is finalized.

APP_LAUNCH flow

The APP_LAUNCH flow is for launching the Swedish BankID app on a mobile device or a desktop computer. You can only launch the app on the same device as you are displaying the launch button.

The process is as follows:

1. Create a new session with sbid_flow set to APP_LAUNCH (as a convenience you can actually use QR as well, if you want to show both a QR code and a launch button in your UI)
2. Take the autoStartToken from the initial response and build a launch URL as described in the Status table above. Display a launch button/link with that URL.
3. Poll for status every 1 to 3 seconds. If you receive the top level status WAITING_FOR_USER:
   • If idpData.sbidStatus is OUTSTANDING_TRANSACTION or NO_CLIENT you should still display the launch button and keep polling.
   • For other values of idpData.sbidStatus, see the description in the the Status table above for information on what to show. Continue polling until the value for status is either SUCCESS, ABORT, or ERROR, at which point the session is finalized.