# Overview

This guide 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 interact with our ID-Card API's.

> **Note**
>
> For an overview of the terms used in this documentation please see [Dictionary](https://docs.stoe.no/id-card/dictionary.md)

## Flow

The flow is triggered by a user or customer presenting a QR-code through BankID App. The consumer that wants to validate
the user's ID, from here reference to as the **Merchant**, reads the QR-code and gets a **sessionId**.
This sessionId is one-time use, and valid for 30 seconds.
The merchant then authorizes 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.

```mermaid
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.
> You can apply for access through our [STØ Portal](https://portal.stoe.no)

## 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](https://docs.stoe.no/id-card/assets/qrcode.jpg)

### 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](https://docs.stoe.no/id-card/getting-started/authentication.md)

### 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` **
>
> ```properties
> POST https://visleg-test-merchantservice-cnhvehb0cvdgggah.z01.azurefd.net/api/merchant/session
>     &Authorization=Bearer <AuthorizationToken>
>     &Payload={"SessionId": "<SessionId>"}
> ```

> **Example Response**
>
> ```json
> 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](https://docs.stoe.no/id-card/API/ID-Card%20API.md).

### 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](https://docs.stoe.no/id-card/getting-started/testing-api.md) and the postman-collection provided.