Skip to main content

Headless flow

This page 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.

Set up the API client​

1. Get client credentials​

Before you can make a request to the Authentication REST API, you need to set up an API client to obtain client credentials. How to do this is described in Accessing Signicat API products > Set up an API client.

2. Obtain access token​

You use the client credentials in a request to obtain an access token. The access token needs to be passed in as an HTTP Bearer authentication header when sending the requests. For more details, see Accessing Signicat API products > Obtaining an access token.

The access token needs to be passed in as an HTTP Bearer authentication header when sending the requests.

Implement the authentication flow​

1. Build the authentication request (CreateSession)​

This section describes how to send a request to the CreateSession endpoint, to create a session and start an authentication.

To begin the authentication flow, your application must first start a session by utilising the CreateSession endpoint. The endpoint will automatically create a session when you send a request. The flow and resulting information from the transaction depends on the parameters you pass in the body. The response from this endpoint will contain an authentication URL, to which you can redirect the end-user to start their transaction.

To create a session, send a POST request to https://api.signicat.com/auth/rest/sessions?signicat-accountId={accountId}.

You can find your accountId in the Signicat Dashboard.

The following sub-sections show examples and descriptions of attributes that you can include in the request.

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": "VGVzdCBpbnRlbnRpb24gdGV4dAo="
    },
    "prefilledInput": {
        "nin": "1234567890"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ]
}

Request example: Phone flow​

Important

When using the Phone flow, you must prefill the nin (national identity number) of the user, otherwise the transaction will fail. You can prefill nin in the prefilledInput object in the request. See Prefill user information for more information.

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:

For more detailed field descriptions, see the API reference.

Control the user flow (additionalParameters)​

You use additionalParameters to control the headless flow:

User information (requestedAttributes)​

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

You add them in the requestedAttributes as shown in the request examples above.

Prefill user information (prefilledInput)​

You can use the prefilledInput parameter to prefill the national identity number of the end-user. If this is prefilled, only the user of that nin value will be able to authenticate.

This is not a required parameter, unless using the Phone flow. Then prefilling is mandatory.

Only for nin

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

Example: "prefilledInput": {"nin": "1234567890"}

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.

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​

2. Obtain user information (GetSession)​

You use the GetSession endpoint to poll for information regarding the session and ongoing authentication.

Once the authentication is successful, the response will contain the user information requested in the CreateSession call that was done earlier.

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.

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.

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​
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 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​

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.
  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.

Next steps​

Dive deeper into Authentication REST API and improve your application with advanced security features:

Signicat Authentication REST API
Find out more about available flows in the eID Hub documentation
API reference
Look up endpoint and parameter details in the reference guide
Last updated:
On this page