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 28th of October 2025, API version 1, 2 and 3 will be disabled. Only clients compatible with API version 4 will continue working. See announcement.
Available versions¶
Versions includes all changes from previous versions.
API Version 4¶
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 is included, in addition to:
- 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 ofsid
and is being removed from Access and ID token. You can find the same data insid
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 oflogin_hint=BID
. E.g. useacr_values=urn:bankid:bid
for BankID on LOA 4.
API Version 3 (disabled from 28th of October 2025)¶
- 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 toBearer
in token response. (Note: OAuth2 specification states this to be case-insensitive).
API Version 2 (disabled from 28th of October 2025)¶
- 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, disabled from 28th of October 2025)¶
- 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.