Skip to main content

Headless flow

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

Prerequisites​

  1. Follow the steps on the Initial preparations page to establish a connection with Swedish BankID.

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

    Want to learn more?

    To learn more about the Signicat Authentication REST API, see:

Implement the authentication flow​

1. Build the authentication request​

This section describes how to make an HTTP POST request to the /sessions endpoint, to create a new session and start an authentication.

To begin the authentication flow, your application must first start a session by utilising the /sessions endpoint. The endpoint automatically creates 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 contains an authentication URL, to which you can embed in an iframe and present to 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​

Here is an example request body for a headless authentication with QR code. This example also applies to App Launch (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=",
        "sbid_intention_text_format": "simpleMarkdownV1",
    },
    "prefilledInput": {
        "nin": "1234567890"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ]
}

Request example: Payment​

Important

When using the Payment feature in the headless flow, you must prefill the nin (national identity number) of the user, otherwise the transaction will fail. See Prefill user information for more information.

Here is an example request body for the BankID Payment headless flow:

{
    "flow": "headless",
    "allowedProviders": [
        "sbid"
    ],
    "prefilledInput": {
        "nin": "123456789000"
    },
    "additionalParameters": {
        "sbid_auth_type": "PAYMENT",
        "sbid_flow": "PAYMENT_NIN",
        "sbid_intention_text": "VGhpcyBpcyBhIHNpbXBsZSBwcmVmaWxsZWQgaW50ZW50aW9uIHRleHQgd2l0aCBTd2VkaXNoIGxldHRlcnMgw6TDtsOlw4TDlsOFDQorIFRoaXMgaXMgdGhlIGZpcnN0IGJ1bGxldCBwb2ludA0KKyBUaGlzIGlzIHRoZSBzZWNvbmQgYnVsbGV0IHBvaW50DQorIFRoZXJlJ3MgZXZlbiBhIHRoaXJkIGJ1bGxldCBwb2ludCE=",
        "sbid_intention_text_format": "simpleMarkdownV1"
    },
    "paymentPrefillData": {
        "reference": "composite-payment-1234",
        "payments": [
            {
                "reference": "individual-payment-5678",
                "amount": "100",
                "currency": "SEK",
                "receiver": "Example Company Ltd",
                "attributes": [
                    {
                        "name": "riskWarning",
                        "value": "largeAmount"
                    },
                    {
                        "name": "riskFlags",
                        "value": "largeAmount, suspiciousPaymentPattern"
                    },
                    {
                        "name": "transactionType",
                        "value": "card"
                    }
                ]
            }
        ]
    },
    "requestedAttributes": [
        "nin",
        "name",
        "firstName",
        "lastName",
        "idpId",
        "dateOfBirth",
        "sbidDeviceIp",
        "sbidCertificateNotBefore",
        "sbidCertificateNotAfter",
        "sbidOcspResponderId",
        "sbidOcspResponse",
        "sbidXmlSignature",
        "sbidMrtd"
    ]
}

Payment attributes

In addition to the "normal" authentication attributes, Payment includes paymentPrefillData attributes. For more details about the specific Payment attributes, see the Payment data section below.

Request example: BankID in telephone calls (Phone)​

Important

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

Here is an example request body for the BankID Phone headless 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"
    }   
}

Request example: "Risk indicator" add-on​

Here is an example request body for an authentication with the Risk indicator (add-on), where risk is added to the requestedAttributes:

{
    "allowedProviders": ["sbid"],
    "flow": "headless",
    "additionalParameters": {
        "sbid_flow": "QR",
        "sbid_end_user_ip": "123.123.123.123"
    },
    "prefilledInput": {
        "nin": "1234567890"
    },
    "requestedAttributes": [
        "name",
        "nin",
        "risk"
    ]
}

If the authentication completes successfully, then the final result contains the attributes that were requested. The risk indication values contain the risk evaluation from SBID, and can be either high, medium, or low.

Want to learn more?

For a feature description, see the Risk indicator (add-on) section on the About page.

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 user information in the requestedAttributes object:

Prefill user information (prefilledInput)​

You can use the prefilledInput parameter to prefill the national identity number of the end-user, for example:

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

Only for nin
  • You cannot prefill other user data than nin for Swedish BankID.
  • Prefilling of nin is required for the Phone and Payment headless flows. It is not required for the redirect or embedded flows.

If you prefill nin, the following will happen:

  • In normal authentication, the transaction is locked down to a specific end-user. Only the user with that nin can authenticate.
  • In a flow with an input field for NIN (Phone and Payment) in the user interface, this number will be filled in automatically.
Payment data (paymentPrefillData)​

You must prefill data about the payment in the paymentPrefillData object in the "Create a new session" request. In this object, you can also provide specific attributes to impact the transaction. Available Payment attributes are riskWarning, riskFlag and transactionType (see detailed descriptions in the below table). Here is an example of a complete paymentPrefillData object:

{...},
  "paymentPrefillData": {
        "reference": "composite-payment-1234",
        "payments": [
            {
                "reference": "individual-payment-5678",
                "amount": "100",
                "currency": "SEK",
                "receiver": "Example Company Ltd",
                "attributes": [
                    {
                        "name": "riskWarning",
                        "value": "largeAmount"
                    },
                    {
                        "name": "riskFlags",
                        "value": "largeAmount, suspiciousPaymentPattern"
                    },
                    {
                        "name": "transactionType",
                        "value": "card"
                    }
                ]
            }
        ]
    },

These are the available attributes inside the paymentPrefillData object:

Response​

Here is an example response after you have created a session for a QR code headless flow:

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

Make an HTTP GET request to the /sessions endpoint to poll for information regarding the session and ongoing authentication.

Upon successful authentication, a response is returned that contains the user information requested in the "Create a new session" call carried out 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 contains 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, APP_LAUNCH, PAYMENT_NIN and PHONE, using the above information.

QR code​

For QR code, 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​

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.

PAYMENT_NIN​

For PAYMENT_NIN, you must show a NIN input field to the end-user, where the end-user enters their NIN. Passing along nin in the "Create a new session" request will start a transaction on their device.

The process is as follows:

  1. Create a new session with sbid_flow set to PAYMENT_NIN.
  2. Inform the end-user that the transaction has started and ask them to open their BankID app on their mobile device.
  3. Poll for status every 1 to 3 seconds. Continue polling until the value for status is either SUCCESS, ABORT, or ERROR, at which point the session is finalized.

PHONE​

For PHONE, you must show a NIN input field to the support agent, where the support agent enters the end-user's NIN (during a phone call with the end-user). Passing along nin in the "Create a new session" request will start a transaction on the end-user's device.

The process is as follows:

  1. Create a new session with sbid_auth_type set to PHONE.
  2. Inform the support-agent that the transaction has started and ask them to relay this information to the end-user, and also ask the end-user to open the BankID app on their mobile device to identify themselves.
  3. Poll for status every 1 to 3 seconds. 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
On this page