Setup of Digital ID Card from Swedish BankID
This guide shows you how to integrate with Digital ID Card from Swedish BankID (from now referred as "ID card") using the Signicat Authentication REST API headless flow.
Prerequisites
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.
To learn more about the Signicat Authentication REST API, see:
- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.
Add Swedish BankID Digital ID Card in the Dashboard
You do not need any agreement to add this product with a sandbox account. However, before you can start integrating in production, you need to configure access with an onboarding manager. To get help with this, contact us.
To add this product to the list of supported eIDs:
- In the Signicat Dashboard, navigate to Products > eID Hub > eIDs.
- Click + Add new.
- Choose Swedish BankID Digital ID Card in the list.
- Select Add to activate the eID.
You can now continue the setup using the Authentication REST API headless flow.
Set up using the Authentication REST API headless flow
1. Create a session
Request
Below is an example request body for creating a session with verification of the ID card. If the verification completes successfully, the final result will contain the attributes that were requested.
Send a POST request to https://api.signicat.com/auth/rest/sessions. For more information about the "Create a session" endpoint, see the API Reference description.
{
"allowedProviders": ["sbid-idcard"],
"flow": "headless",
"additionalParameters": {
"sbid_idcard_qr_data" : "BANKIDF.74226FAAE..."
},
"requestedAttributes": [
"name",
"firstName",
"lastName",
"nin",
"dateOfBirth",
"sbidAge",
"sbidOcspResponse",
"sbidXmlSignature",
"sbidOcspResponderId",
"sbidVerificationTime",
"sbidVerificationSignature"
]
}
Field descriptions
To initialise a verification of the ID card, you must specify the following required parameters in the initial request:
Additional parameters
Response
Here is an example response for the session creation:
{
"id": "f43fb018-1929-1b49-a891-59ee1d8fcf36",
"accountId": "a-sdge-...",
"status": "CREATED",
"idpData": {},
"allowedProviders": [
"sbid-idcard"
],
"flow": "headless",
"requestedAttributes": [
"name",
"firstName",
"lastName",
"nin",
"dateOfBirth",
"sbidAge",
"sbidOcspResponse",
"sbidXmlSignature",
"sbidOcspResponderId",
"sbidVerificationTime",
"sbidVerificationSignature"
],
"sessionLifetime": 600
}
Errors
2. Get the session status
Request
Send a GET request to https://api.signicat.com/auth/rest/sessions/{id}, where {id} is the id returned when you created the session. For more information about the "Get session status" endpoint, see the API Reference description.
Response
Example response of SUCCESS
{
"id": "c9259246-4405-3341-8be8-d3eb5377272b",
"accountId": "a-sdge-...",
"status": "SUCCESS",
"provider": "sbid-idcard",
"subject": {
"id": "191212121212",
"name": "Tolvan Tolvansso",
"firstName": "Tolvan",
"lastName": "Tolvansson",
"dateOfBirth": "1912-12-12",
"nin": {
"value": "191212121212",
"issuingCountry": "SE",
"type": "PERSON"
},
"sbidVerificationSignature": "LIIm0n9un123456f7js7fs0df...",
"sbidOcspResponderId": "C=SE,O=Testbank A AB (publ),SERIALNUMBER=111111111111,CN=Testbank A Customer CA1 v1 for BankID Test OCSP Signing",
"sbidXmlSignature": "IIm0n9un097089f7js7fs0d8f...",
"sbidOcspResponse": "MIIHfgoBAKCCB3cwggdzBgkrBg...",
"sbidVerificationTime": "06/07/2023 14:18:58",
"sbidAge": "111"
},
"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..."
},
"error": null,
"idpData": {
"sbidStatus": "SUCCESS"
},
"allowedProviders": [
"sbid-idcard"
],
"flow": "headless",
"requestedAttributes": [
"firstName",
"lastName",
"name",
"nin",
"dateOfBirth",
"sbidAge",
"sbidOcspResponderId",
"sbidOcspResponse",
"sbidXmlSignature",
"sbidVerificationTime",
"sbidVerificationSignature"
],
"sessionLifetime": 600
}
Example response of ERROR: VERIFICATION-FAILED
{
"id": "d6ce8018-e4c9-7241-8051-2f2ab8a7da85",
"accountId": "a-sdge-...",
"status": "ERROR",
"error": {
"type": "https://developer.signicat.com/docs/error-codes/",
"title": "Verification of ID card failed.",
"code": "idp:sbid-idcard:idcard-verification-failed"
},
"allowedProviders": [
"sbid-idcard"
],
"flow": "headless",
"requestedAttributes": [
"name",
"firstName",
"lastName",
"nin",
"dateOfBirth",
"sbidAge",
"sbidOcspResponse",
"sbidXmlSignature",
"sbidOcspResponderId",
"sbidVerificationTime",
"sbidVerificationSignature"
],
"sessionLifetime": 600
}
Example response of ERROR: INVALID-QR-CODE
{
"id": "dce36b22-71e5-1f44-8ae4-7c631f96ecda",
"accountId": "a-sdge-...",
"status": "ERROR",
"error": {
"type": "https://developer.signicat.com/docs/error-codes/",
"title": "The request contained an invalid QR code",
"detail": "The passed qrCode has expired or is in other way invalid. QR codes expires within some seconds, and must be consumed within a period of time",
"code": "idp:sbid-idcard:invalid-qr-code"
},
...
}
Example response of ERROR: RP-SERVICE-ERROR
{
"id": "dce36b22-71e5-1f44-8ae4-7c631f96ecda",
"accountId": "a-sdge-...",
"status": "ERROR",
"error": {
"type": "https://developer.signicat.com/docs/error-codes/",
"title": "An error occurred when contacting the external BankID service",
"code": "idp:sbid-idcard:rp-service-error"
},
...
}
Example response of ERROR: UNKNOWN-ERROR
{
"id": "dce36b22-71e5-1f44-8ae4-7c631f96ecda",
"accountId": "a-sdge-...",
"status": "ERROR",
"error": {
"type": "https://developer.signicat.com/docs/error-codes/",
"title": "Unknown error",
"code": "idp:sbid-idcard:unknown-error"
},
...
}