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 default version of the BankID APIs is 1.

Minimum version will be 4

From 28^th of October 2025, API version 1, 2, 3 and 4 will be active by default. Only clients compatible with API version 4 will continue working. See announcement.

Available versions

New API Versions contains all changes from older versions. E.g. v4 includes changes from v1->v3.

API Version 4 (enforced from 28^th of October 2025)

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

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) 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

• 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 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 minimum version for your OIDC Client, without the need to include it in the authorize request.