Skip to main content

Redirect flow

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

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: Remote flow (QR)​

Here is an example request body for an authentication, using the remote flow (QR code).

{
    "allowedProviders": ["sbid"],
    "flow": "redirect",
    "additionalParameters": {
        "sbid_initial_flow": "REMOTE_FLOW",
        "sbid_intention_text": "VGVzdCBpbnRlbnRpb24gdGV4dAo="
    },
    "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.

If the authentication completes successfully, the final result will contain the attributes that were requested.

Request example: Remote flow (QR) with MRTD​

Here is an example request body for an authentication, where the MRTD security check is added to the normal QR code flow. This reqest will result in an MRTD transaction.

Important

When setting the additional parameter sbid_require_mrtd to true, remember to also add sbidMrtd in reqestedAttributes. If you do not set both parameters, the transaction will fail. You must also validate that the sbidMrtd value is returned as true to prevent any tampering with the sbid_require_mrtd parameter.

{
    "flow": "redirect",
    "allowedProviders": [
        "sbid"
    ],
    "additionalParameters": {
        "sbid_initial_flow": "REMOTE_FLOW",
        "sbid_require_mrtd": "true"
    },
    "requestedAttributes": [
        "name",
        "nin",
        "sbidMrtd"
    ],
    "callbackUrls": {
        "success": "https://signicat.com",
        "abort": "https://example.test/abort",
        "error": "https://example.test/error"
    }
}

If the authentication completes successfully, the final result will contain the attributes that were requested.

For a feature description of the MRTD check, see the About page.

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:

For more detailed field descriptions, see the API Reference.

Control the user flow (additionalParameters)​

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

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

End-user authentication​

The end-user follows these steps:

  1. On your website/application, the end-user clicks on a button to authenticate with BankID. Your application sends a request to start an authentication with BankID, as described in the previous section.
  2. The end-user is redirected to the BankID login page.
  3. The end-user logs in using their BankID credentials (this step may involve two-factor authentication).

After the end-user approves the request, the browser is redirected back to the relevant callbackUrl specified in the CreateSession request.

For screen examples, see About Swedish BankID.

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​

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": "Sven",
        "lastName": "Svensson",
        "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​

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 identity provider was actually used by checking the provider field. This can be useful if you allowed more than one identity provider when you created the session.

Success

You have now completed an authentication redirect flow with Swedish BankID.

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