Redirect flow
This guide shows you 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.
Prerequisites
- Follow the steps on the Initial preparations page to establish a connection with Swedish BankID.
-
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:
- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.
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 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 redirect 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": "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: "Extra control" add-on
Here is an example request body for an authentication, where "Extra control" is added to the normal remote flow. With the "Extra control" add-on, the user is required to scan their MRTD (Machine Readable Travel Document) with the BankID app.
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 malicious 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, see the About page.
Request example: BankID in telephone calls (Phone)
Here is an example request body for an authentication with the Phone feature:
{
"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"
}
}
Request example: "Risk indicator" add-on
Here is an example request body for an authentication with the Risk indicator (add-on), where riskis added to the requestedAttributes:
{
"allowedProviders": ["sbid"],
"flow": "redirect",
"requestedAttributes": [
"name",
"nin",
"risk"
],
"callbackUrls": {
"success": "https://example.com/success",
"abort": "https://example.com/abort",
"error": "https://example.com/error"
}
}
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.
For a feature description, see the Risk indicator (add-on) section on the About page.
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 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"}
nin- You cannot prefill other user data than
ninfor Swedish BankID. - Prefilling of
ninis 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
nincan authenticate. - In a flow with an input field for NIN (Phone and Payment) in the user interface, this number will be filled in automatically.
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:
- 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.
- The end-user is redirected to the BankID login page.
- 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
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
The response contains 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"
},
"risk": {
"thirdPartyEvaluation": {
"riskValue": "low",
"source": "sbid"
}
}
},
"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.
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: