Skip to content

Overview

This guid will help you get started integrating ID-Card into your application.

ID-Card uses OpenID Connect protocol for authentication, it builds on OAuth 2.0 authorization framework. This section describes how to authorize your application, and how with our ID-Card API's.

Note

For an overview of the terms used in this documentation please see Dictionary

Flow

The flow is triggered by a user or customer presenting a QR-code through BankID App. The consumer that wants to validate the users ID, from here reference to as the Merchant, reads the QR-code and gets a sessionId. This sessionId is one-time use. Read more about the sessionId here. The merchant then authorize against BankID OIDC to get a access token. This token is then used, together with sessionId, in requests to ID-Card API to retrieve data about the user.

sequenceDiagram
    actor u as User/Customer
    participant m as Merchant backend application
    participant b as BankID OIDC
    participant v as ID-Card API    

    u->>m : User presents a QR-code
    m->>m : Read QR-code and retrieve the embedded sessionId
    m->> b: Request BankID OIDC for a token
    b-->> m: Obtain access token
    m->> v: Request session detail with BankID access token and sessionId
    v -->> m: Obtain session detail

Prerequisites

You need to be provided with a client_id, client_secret and scope to request an access token. Please contact us to get access.

Implementation Steps:

1. Get a SessionId

  1. Scan the QR Code: Use a QR code scanner or an optical reader to read the QR code.
  2. Extract the string: Extract the string contained in the QR code.
  3. Verify the string: SessionId should look something like this:
    "VisLeg-9fa44f41-ce68-4f03-bc1a-498b00cf5fec"
    Verify that the GUID starts with "VisLeg". If not, then discard it.

Example of a genuine QR code

Image Title

2. Authentication Request

The authentication should be done backend-to-backend, not in merchant frontend. The credentials will be provided after agreement. For more details on how to implement and code examples, see Authentication

3. Session Request

In this step we are retrieving user data using SessionId from ID-Card API. The response will only return the data the merchant has a need for. If a merchant only needs Age of a user, the rest of the fields will be empty. This is controlled by the scope provided in the authentication request.

In this example we have the scope: identity_picture_age when we asked for the access token. So when we request user data, only documentPhoto and age are filled with values.

Example Request with scope: identity_picture_age 

POST https://visleg-test-merchantservice-cnhvehb0cvdgggah.z01.azurefd.net/api/merchant/session
    &Authorization=Bearer <AuthorizationToken>
    &Payload={"SessionId": "<SessionId>"}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "firstName": "",
    "lastName": "",
    "documentPhoto":"<base64string>",
    "age": 20
}

Note

For more details about the API and the model see API Documentation.

4. Testing the Integration

To help with testing the integration, we have create an endpoint that returns QR-codes to be used for testing. They need to be generated and then used the same way as a regular flow.

For more details please see the test documentation and the postman-collection provided.