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:

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.

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.

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 page.
sbid_require_mrtd	true or false	Setting this parameter to true, will enforce the end-user to do an additional confirmation with either their Swedish ID-Card or their Swedish passport. This should be used in transactions where extra security might be warranted, for example high risk transactions. When this is set to true, you must also include sbidMrtd in the requestedAttribute. Note: You must validate that the sbidMrtd value is returned as true to prevent any tampering with the sbid_require_mrtd parameter. For feature details, see the About page page.
sbid_auth_type	NORMAL or PHONE	Controls which type of flow is started for Swedish BankID: - NORMAL launches 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, enable the Phone flow in the Dashboard configuration and prefill nin for the user (see Prefill user information).
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	VGVzdCBpbnRlbnRpb24gdGV4dAo=	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

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.

Attribute	sub-field	Example value in response	Description
name		Sven Svensson	The full name of the end-user
firstName		Sven	The first name of the end-user.
lastName		Svensson	The surname of the end-user.
dateOfBirth		1990-02-17	The date of birth of the end-user (ISO 8601 format).
idpId		199002171234	Personal identifier set by the identity provider.
nin	value	199002171234	The national identity number (“personnummer”) of the end-user.
	type	PERSON	The type of national identity number. Always PERSON for Swedish BankID.
	issuingCountry	SE	The issuing country of the national identity. Always SE for Swedish BankID.
sbidDeviceIp		3.127.53.67	The IP address of the end-user's device where the BankID app was run during the authentication.
sbidCertificateNotBefore		2022-10-18T22:00:00.000Z	The time from when the certificate is valid.
sbidCertificateNotAfter		2023-10-19T21:59:59.000Z	The time the certificate expires.
sbidOcspResponderId		C=SE, O=Testbank A AB (publ), SERIALNUMBER=111111111111, CN=Testbank A Customer CA1 v1 for BankID Test OCSP Signing	The responder ID of the certificate used to sign the OCSP response (extracted from sbidOcspResponse).
sbidOcspResponse		MIIHfgoBAKCCB3cwggdzBgkrBgEF...	Base64 encoded OCSP response for end user's BankID certificate
sbidXmlSignature		PD94bWwgdmVyc2lvbj0iMS4wIiBl...	Base64 encoded XML signature returned by BankID as proof of authentication
sbidMrtd		true	Required in the MRTD check when the sbid_require_mrtd additional parameter is set to true. Note: You must validate that the sbidMrtd value is returned as true to prevent any tampering with the sbid_require_mrtd parameter.

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

Status	Description
CREATED	The user has not completed the authentication yet.
SUCCESS	The authentication is successful. Authentication result is present in the response.
ABORT	The session was cancelled by the end-user.
ERROR	Something went wrong during the session, or the 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 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