API Versions#

On this page

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.

This version adds many changes related to BankID Server end-of-life and recommendations from the OIDC specification⁠ (opens in a new tab) and FAPI 2.0⁠ (opens in a new tab).

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 and an optional Permission Grant replaces this need.
It is required to use PKCE (Proof Key for Code Exchange)⁠ (opens in a new tab) in Authorization Code flow based on recommendations in the OIDC specification⁠ (opens in a new tab). 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 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⁠ (opens in a new tab).
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⁠ (opens in a new tab).
Specifying NNIN in query param login_hint is no longer supported. Use PAR or encrypted response object instead.
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.

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⁠ (opens in a new tab).
token_type value has been capitalized to Bearer in token response. (Note: OAuth2 specification states this to be case-insensitive).

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⁠ (opens in a new tab).

To set which API Version to use, include the version in the authorize request using:

api_version=[version]

Example:

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