Getting Started¶

Access to the BankID eSign APIs¶

To access the BankID eSign 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.
`esign`	Access to the SignDoc API.
`signdoc/read_write`	Inherited from BankID OIDC SignDoc, provides same access as `esign`.
`esign/qtsa`	Access to the Qualified Timestamping API.
`esign/nnin`	Provides access to Norwegian National Identity Numbers ("Fødselsnummer") from the user. See Certificate and PKI for more information.

1. Register a client with BankID OIDC¶

You need a client registered at BankID OIDC. Follow the instructions here to register your application and obtain the necessary client credentials (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:

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

Send an HTTP GET request to the respective configuration URL using your preferred programming language or API tool.
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)
```
{
  ...
  "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:

Retrieve the token endpoint URL token_endpoint dynamically from the OIDC configuration.
Call the token endpoint URL with your client credentials.

You can find more detailed information about acquiring access tokens in the BankID OIDC documentation.

In the scope field, include the any of the scopes listed depending on the API you want to access.

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. Instructions on how to create test users can be found here