# API Versions

BankID provide API versioning. This allows us to introduce new features and improvements without breaking existing
implementations.

The version is an integer that is returned in all tokens as `api_ver` claim.

## Current version

The default version of the BankID APIs is `4`.

> **Minimum version recently changed to 4**
>
> From 5th of November 2025, all clients were forced to use at minimum [API Version 4](https://docs.stoe.no/bankid-oidc-provider/api-versions.md#api-version-4).

## Available versions

> **Newer API Versions include **all changes** from older versions. E.g. v4 includes changes from v1->v3.**

### API Version 4 (enforced from 5th of November 2025)

This version adds many changes related to BankID Server end-of-life and recommendations from the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RequestObject) and [FAPI 2.0](https://openid.net/specs/fapi-2_0-security-02.html).

**All changes from Version 1 to 3 are included**, in addition to:

- The end-of-life announcement of BankID Server will cause some claims to be removed from Tokens:
  - `additionalCertInfo`
  - `tid `

- BankID Proof is being removed due to BankID Server end-of-life. The [signed ID token](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/bankid-proof.md) and an optional [Permission Grant](https://docs.stoe.no/bankid-with-biometrics/flows/code-flow-for-payments.md#8-get-the-signed-permission) replaces this need.

- It is required to use [PKCE (Proof Key for Code Exchange)](https://oauth.net/2/pkce/) in Authorization Code flow based on [recommendations in the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RequestObject). However, Azure B2C customers can opt-out of PKCE due to lack of support. Contact us, if you fall in this category.

- The following parameters in [Authorization Code flow](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md) are always required:
  - `response_type`
  - `state`
  - `nonce`

- `response_type` is required as a query parameter in the authorize request when using request objects for [compliance with OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RequestObject).

- The `session_state` claim is a duplicate of `sid` and is being removed from Access and ID token. You can find the same data in `sid` claim.

- The `nonce` claim is being removed from Access token as per the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html).

- Specifying NNIN in query param `login_hint` is no longer supported. Use [PAR or encrypted response object instead](https://docs.stoe.no/bankid-oidc-provider/core-concepts/login-hint.md).

- Use `acr_values` to select Level of Assurance instead of `login_hint=BID`. E.g. use `acr_values=urn:bankid:bid` for BankID on LOA 4.

### API Version 3

- All Tokens are signed using ES256 signature algorithm. Make sure your system can handle validation of these signatures.
- `acr_values` parameter of the authorize endpoint now supports multiple ACR values (space-separated) for [compliance with OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
- `token_type` value has been capitalized to `Bearer` in token response. (Note: OAuth2 specification states this to be case-insensitive).

### API Version 2

- Added custom `api_ver` claim to tokens.
- `amr` claim has changed from a String to an array of Strings. E.g. from "BID" to `["bid"]` for [compliance with OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken).

### API Version 1

- Initial version of the BankID APIs. No backwards incompatible changes.

## How to enable a new version

To set which API Version to use, include the version in the [authorize request](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md) using:

```
api_version=[version]
```

Example:

```
GET [authorize_url]?client_id=myclient-bankid-prod&scope=openid&api_version=3
```

> **Tip**
>
> You can also make a request to [support](https://docs.stoe.no/bankid-oidc-provider/resources/support.md) to set the minimum version for your OIDC Client,
> without the need to include it in the authorize request.