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 (from version 2).

Current version

Today, the current version of the BankID APIs is 1.

Current version will be 4

In October 2025, the default version will be changed to 4 for ALL clients. See announcement.

Available versions

Versions includes all changes from previous versions.

API Version 4 (default from October 2025)

This version adds many changes related to BankID Server end-of-life and recommendations from the OIDC specification and FAPI 2.0.

• The end-of-life announcement of BankID Server will cause some claims to be removed from Tokens:
  • originator
  • 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) in Authorization Code flow based on recommendations in the OIDC specification.

• 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.

• 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.
• 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.

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.
• 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.

API Version 1 (default)

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

How to enable a new version

To enable a new version you need to 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

Tip

You can also make a request to support to set the default version for your OIDC Client, without the need to include it in the authorize request.