# Setup of Digital ID Card from Swedish BankID

You integrate with Digital ID Card from Swedish BankID (from now referred as"ID card") using the Signicat Authentication REST API headless flow.

This page describes the specifics for setting up this product. For more general information about the Authentication REST API, see the Authentication REST API page.

Contents

Initial preparations
Add Swedish BankID Digital ID Card in the Dashboard
Set up using the Authentication REST API headless flow

# Initial preparations

The setup descriptions below assume you have completed the following initial preparations:

Sign up to the Signicat Dashboard (opens new window).
In the Signicat Dashboard, set up an organisation, an account and a domain.

Sandbox account

We recommend you to create a sandbox account to test our services before implementing them in production.

# Add Swedish BankID Digital ID Card in the Dashboard

Sign an agreement

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 (opens new window).

To add this product to the list of supported ID methods:

In the Signicat Dashboard, go to eID Hub > ID Methods (opens new window).
Click Add new.
Choose Swedish BankID Digital ID Card in the list and click Save.

You can now continue with setting it up via the Authentication REST API using the headless flow.

# Set up using the Authentication REST API headless flow

# 1. Set up the API client

Before you can make a request to the Authentication REST API, you need to set up an API client to obtain client credentials. You use these client credentials in a request to obtain an access token. How to do this is described in the Accessing Signicat API products section. The access token needs to be passed in as an HTTP Bearer authentication header when doing the requests in step 2 and 3.

# 2. 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 (opens new window) 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:

Field	Required	Example value	Description
`allowedProviders`	Yes	`["sbid-idcard"]`	MUST have the value `["sbid-idcard"]`.
`flow`	Yes	`headless`	MUST have the value `headless`.

# Additional parameters

Field	Required	Example value	Description
`sbid_idcard_qr_data`	Yes	`"BANKIDF.74226FAAE3E64E70BB03F8E8E18D0439.8.79C416AA74278A70FAC25855F728A3206789B87B6FF6EB00688DB9622EFD2D33"`	The content of the scanned QR code you want to verify

# 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

HTTP Status Code	Error code	Description
400	`idp:request-validation-failed`	A mandatory additional parameter was missing.
500	`idp:server-problem`	Internal server error occurred while creating the session.

# 3. 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 (opens new window) 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/identity-methods/sbid/errors.html#idp:sbid:idcard-verification-failed",
        "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/identity-methods/sbid/errors.html#idp:sbid:invalid-qr-code",
        "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/identity-methods/sbid/errors.html#idp:sbid:rp-service-error",
        "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/identity-methods/sbid/errors.html#idp:sbid:unknown-error",
        "title": "Unknown error",
        "code": "idp:sbid-idcard:unknown-error"
    },
    ...
}

# Errors

HTTP Status Code	error.code	Description
500	`idp:server-problem`	Internal server error occurred while getting the session.

← About Digital ID Card from Swedish BankID