# Getting Started

## Access to the BankID Signing APIs

To access the BankID Signing APIs the merchant must have a BankID OIDC client with any of the following scopes:

| Scope             | Description                                                                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `esign/csc`       | Access to the [Cloud Signature Consortium (CSC) API](https://docs.stoe.no/bankid-esign-provider/apis/csc/CSC.md).                                                                 |
| `esign`           | Access to the [WYSIWYS API](https://docs.stoe.no/bankid-esign-provider/apis/signdoc/signdoc-intro.md).                                                                            |
| `esign/qualified` | Access to the [WYSIWYS API](https://docs.stoe.no/bankid-esign-provider/apis/signdoc/signdoc-intro.md).                                                                            |
| `esign/qtsa`      | Access to the [Timestamping API](https://docs.stoe.no/bankid-esign-provider/apis/timestamp/timestamp.md).                                                                         |
| `esign/nnin`      | Provides access to Norwegian National Identity Numbers ("Fødselsnummer") from the user.                                                                                           |
| `esign/b2b`       | Access to the [B2B signing API](https://docs.stoe.no/bankid-esign-provider/apis/b2b/v0/b2b-bankid-signer-api.md). **Requires DPOP protocol and `private_key_jwt` authentication** |
|                   |                                                                                                                                                                                   |

### 1. Register a client with BankID OIDC

You need a client registered at [BankID OIDC](https://docs.stoe.no/bankid-oidc-provider/introduction.md). Follow the instructions
[here](https://docs.stoe.no/bankid-oidc-provider/resources/provisioning.md) to register your
application and obtain the necessary [client credentials](https://tools.ietf.org/html/rfc6749#section-1.3.4) (`client_id` and `client_secret`).
You will need two clients, one for the test environment and one for the production environment.

### 2. Get the BankID OpenID Connect Configuration

To ensure seamless integration with BankID OIDC and avoid hardcoding specific endpoints in you application, follow these
steps to dynamically fetch the [OpenID Connect configuration](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig):

1. Determine the appropriate configuration URL based on the environment:

   | Environment                       | URL                                                                                   |
   | --------------------------------- | ------------------------------------------------------------------------------------- |
   | Production                        | <https://auth.bankid.no/auth/realms/prod/.well-known/openid-configuration>            |
   | Current (public test environment) | <https://auth.current.bankid.no/auth/realms/current/.well-known/openid-configuration> |

2. Send an HTTP GET request to the respective configuration URL using your preferred programming language or API tool.

3. Capture the response which will contain a JSON document with the configuration. By dynamically fetching the OIDC configuration, your application remains flexible allowing for future changes or updates to the endpoints without requiring modifications to your code.

   > **Example response from Current (relevant fields only)**
   >
   > ```json
   > {
   >   ...
   >   "token_endpoint": "https://auth.current.bankid.no/auth/realms/current/protocol/openid-connect/token",
   >   ...
   > }
   > ```

   _This is a sample response. The actual response may differ._

### 3. Get an access token from BankID OIDC

To obtain an access token from OIDC, follow these steps:

1. Retrieve the token endpoint URL `token_endpoint` dynamically from the OIDC configuration.

2. Call the token endpoint URL with your client credentials.

You can find more detailed information about acquiring access tokens in the [BankID OIDC documentation](https://docs.stoe.no/bankid-oidc-provider/api/token.md).

3. In the scope field, include the any of the [scopes listed](https://docs.stoe.no/bankid-esign-provider/getting-started.md#access-to-the-bankid-esign-apis) depending on the API you want to access.

   Separate multiple scopes with a space.

Here's an example of a valid request in the `current` environment
(replace placeholder in Authorization header with your own credentials):

````
```http
POST /auth/realms/current/protocol/openid-connect/token HTTP/1.1
Host: auth.current.bankid.no
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <Base64-encoded client id:client secret>

grant_type=client_credentials&scope=esign%2Fcsc
```
````

## BankID Test users

Create BankID test users in [BankIDs preprod environment](https://ra-preprod.bankidnorge.no/#/generate). Instructions on how to create test users can be found [here](https://bidbax.atlassian.net/wiki/spaces/DEVPUB/pages/29232606/RA+Light+User+Guide)

## eSign test client for merchants

We provide a test client for merchants to easily test the BankID signing APIs without having to implement their own client application. The test client is available in the preprod environment and can be accessed using the following link: [eSign Test Client](https://web-test.preprod.esign-stoetest.cloud/merchant)