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.

Initial preparations

If you don't have an account already, sign up for a free Signicat account by completing the following initial preparations:

1. Sign up to the Signicat Dashboard and register your profile. For more details, see the Get started with Signicat guide.
2. In the Dashboard, make sure you have set up an organisation and an account.
3. Additionally, to use this product, you must set up a domain.

Accounts: Test in sandbox, go live in production

We recommend you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately.

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.

To add this product to the list of supported eIDs:

1. In the Signicat Dashboard, navigate to Products > eID Hub > eIDs.
2. Click + Add new.
3. Choose Swedish BankID Digital ID Card in the list.
4. 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. 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 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

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 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