Embedded flow
This guide shows you how to embed the Swedish BankID authentication inside an iframe in your own flow (as opposed to redirecting to another page).
The embedded flow is only supported for the Payment add-on.
If you want access to the Payment add-on, please contact us by creating a support ticket in the Signicat Dashboard.
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 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 new 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: Payment
Here is an example request body for the BankID Payment embedded flow:
{
"flow": "embedded",
"allowedProviders": [
"sbid"
],
"embeddedParentDomains" : ["someparentdomain.example"],
"returnUrl": "https://example.com/",
"additionalParameters": {
"sbid_auth_type": "PAYMENT",
"sbid_initial_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"
}
]
}
]
},
"requestedAttributes": [
"nin",
"name",
"firstName",
"lastName",
"idpId",
"dateOfBirth",
"sbidDeviceIp",
"sbidCertificateNotBefore",
"sbidCertificateNotAfter",
"sbidOcspResponderId",
"sbidOcspResponse",
"sbidXmlSignature",
"sbidMrtd"
]
}
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.
Upon sending this request, the BankID session will start.
If the authentication completes successfully, the final result will contain the attributes that were requested.
Attribute descriptions
To initialise an authentication with Swedish BankID, you can use the following attributes in the initial request:
For more detailed field descriptions, see the API reference.
Control the user flow (additionalParameters)
You use additionalParameters to control the embedded 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.
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 Payment embedded flow:
{
"id": "0b325626-99d5-4aa3-8e8f-f48ab317167a",
"accountId": "a-sdge-oyNgetJTcOc5ba7Sj5ZR",
"authenticationUrl": "https://api.signicat.com/idps/sandbox/sbid/embedded/ui/b4099adc-073a-1a4c-b65d-962759410010/init?messageId=291aefec-79d2-4aab-bf95-3cfb927de3e9",
"status": "CREATED",
"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"
}
]
}
]
},
"allowedProviders": [
"sbid"
],
"requestedAttributes": [
"dateOfBirth",
"firstName",
"idpId",
"lastName",
"name",
"nin",
"sbidCertificateNotAfter",
"sbidCertificateNotBefore",
"sbidDeviceIp",
"sbidMrtd",
"sbidOcspResponderId",
"sbidOcspResponse",
"sbidXmlSignature"
],
"sessionLifetime": 1200,
"expiresAt": "2025-03-31T12:22:10.8247473+00:00"
}
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 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 BankID login page is opened in an iframe inside your website/application.
- The end-user logs in using their BankID credentials (this step may involve two-factor authentication).
After the end-user has finished the authentication in the iframe, the iframe is redirected to the returnUrl specified in the "Create a new session" request.
During certain error situations the user will also be redirected to the returnUrl, and more information regarding the error will be available by getting the session information as explained below.
2. Retrieve the sessionNonce
After the user has finished the authentication and been redirected to your specified returnUrl, you must retrieve the returned sessionNonce value and include it in the GetSession request (see below) to get information about the transaction and the user.
We return the sessionNonce value to ensure that the communication session is unique and cannot be used in replay attacks.
The sessionNonce value is returned at the end of the returnUrl, for example:
https://example.com/?sessionNonce=P-zvdIDsW6ZKGn5__48Df9RitMlxHvUe1RHZ-PLxczc
3. Obtain user information
You use the GetSession endpoint to get information about the session you created earlier. It will contain the user information if the authentication is successful.
Request
No data specific for 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}?sessionNonce={sessionNonceValue}.
Ensure you include the sessionNonce (see the Retrieve the sessionNonce section). 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 indicates the current status of the session. Below you can see an example response for a successfully completed session:
{
"id": "d170293e-af5a-4df9-bc0e-b2668086b75e",
"accountId": "a-sdge-oyNgetJTcOc5ba7Sj5ZR",
"authenticationUrl": "https://api.signicat.com/idps/sandbox/sbid/embedded/ui/72a67b04-12d9-9b4e-b6b8-99efefe47e39/init?messageId=9f2f4c87-4be7-4e05-a67c-3b95e6b04642",
"status": "SUCCESS",
"provider": "sbid",
"subject": {
"id": "M1FPSeZ4ExqTyiWg3itq9FfQ-UBQTHAk-j71dbYS6sg=",
"idpId": "197010175003",
"name": "Laura Jansons",
"firstName": "Laura",
"lastName": "Jansons",
"dateOfBirth": "1970-10-17",
"nin": {
"value": "197010175003",
"issuingCountry": "SE",
"type": "PERSON"
},
"sbidDeviceIp": "193.90.75.182",
"sbidCertificateNotBefore": "2025-03-30T22:00:00.000Z",
"sbidCertificateNotAfter": "2026-03-31T21:59:59.000Z",
"sbidOcspResponderId": "C=SE,O=Testbank A AB (publ),SERIALNUMBER=111111111111,CN=Testbank A Customer CA3 v1 for BankID Test OCSP Signing",
"sbidMrtd": "false",
"sbidOcspResponse": "MIIHdgoBAKCCB28wggdrBgkrBgEFBQcwAQEEggdcMIIHWDCCASyhgYgwgYUxCzAJBgNVBAYTAlNFMR0wGw...",
"sbidXmlSignature": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8..."
},
"loa": "substantial",
"allowedProviders": [
"sbid"
],
"flow": "embedded",
"requestedAttributes": [
"dateOfBirth",
"firstName",
"idpId",
"lastName",
"name",
"nin",
"sbidCertificateNotAfter",
"sbidCertificateNotBefore",
"sbidDeviceIp",
"sbidMrtd",
"sbidOcspResponderId",
"sbidOcspResponse",
"sbidXmlSignature"
],
"sessionLifetime": 1200,
"expiresAt": "2025-03-31T08:31:29.3444528+00:00"
}
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 with Payment.
Next steps
Dive deeper into Authentication REST API and improve your application with advanced security features: