Web service API
SSL certificates
The RP certificate must be installed/configured in your “key store”. It does not need to be verified by your application and the issuer of the RP certificate is not needed. The BankID server will present its server certificate to your application and verification of the RP certificate will be performed during TLS handshake when the channel is established.
The server certificate needs to be verified by your application. To make that verification possible the issuer of the server certificate needs to be installed/configured in your “trust store”. Key stores and trust stores are managed differently depending on your environment and are not explained in this guide.
Different certificates are used for production and test.
The certificates may need to be converted to a different file format to be accepted by your environment.
Your application needs access to your key store and trust store and your application needs to use correct key store and trust store.
Line breaks may need to be removed from the issuer of the server certificate pasted from this guide.
Versions
A new version of the web service API will be published on a new URL every time there is a breaking change in the API. RP should always use the latest version of the API. The general rule is that old versions will be shut down 2 years after the release of the successor, unless shorter time is communicated.
As new functionality is introduced to the system the behaviour of an existing version of the interface may change, e.g., existing faults may also be used in new situations.
Summary of changes by version |
---|
v. 6.0 (May 2023) |
Changes
|
v. 5.1 (April 2020) |
Changes
URL End of life 2024 |
v. 5 (February, 2018) |
Changes
URL End of life 2022 |
Summary of changes by version
Changes
New version of the RP API removing the option to start transaction based on personal number.
Support for identification in phone calls.
Changes
Support for animated QR-codes.
New return parameters to support animated QR codes.
autoStartTokenRequired deprecated.
tokenStartRequired introduced.
URL
https://appapi2.bankid.com/rp/v5.1
End of life
2024
Changes
Http/JSON replaces SOAP/XML
cancel introduced.
URL
https://appapi2.bankid.com/rp/v5
End of life
2022
Breaking change
The following table describes the general principles for breaking changes. Security reasons may shorten the notice period.
Change | Breaking |
---|---|
Add optional in-parameter | No |
We may add additional optional in-parameters without prior notice. |
|
Add required in-parameters | Yes |
We may add additional required in-parameters. This will be done using a new endpoint and with a two year notice. |
|
Remove any in-parameter | Yes |
We may remove support for in-parameters. This will be done using a new endpoint and with a two year notice. |
|
Add return-parameter | No |
We may add additional return-parameters without prior notice. RP must consider this in their implementation. Implementations must not discard the complete response if it includes unknown parameters. |
|
Remove any return-parameter | Yes |
We may remove return-parameters. This will be done using a new endpoint and with a two year notice. |
|
Remove method | Yes |
We may remove methods. This will be done using a new endpoint and with a two year notice. |
|
Add method | No |
We may add new methods without prior notice. |
|
Change issuer of server certificate | Yes |
We may change issuer of the server certificate. This will be done using a new endpoint and with a two year notice. |
|
Add new hintCodes | No |
We may add new hintCode without prior notice. RP must consider this in their implementation. If RP receives an "unknown" hint code a general message should be presented to the user. |
|
Add new errorCodes | No |
We may add new errorCode without prior notice. RP must consider this in their implementation. If RP receives an "unknown" error code a general message should be presented to the user. |
|
Launch the BankID App | Yes |
We may change the method used to launch the BankID App. This will be done by marking the method as deprecated in this guide and, after two years, eventually release new version of the app that does not support the deprecated method. |
Change
We may add additional optional in-parameters without prior notice.
BreakingNo
We may add additional required in-parameters. This will be done using a new endpoint and with a two year notice.
BreakingYes
We may remove support for in-parameters. This will be done using a new endpoint and with a two year notice.
BreakingYes
We may add additional return-parameters without prior notice. RP must consider this in their implementation. Implementations must not discard the complete response if it includes unknown parameters.
BreakingNo
We may remove return-parameters. This will be done using a new endpoint and with a two year notice.
BreakingYes
We may remove methods. This will be done using a new endpoint and with a two year notice.
BreakingYes
We may add new methods without prior notice.
BreakingNo
We may change issuer of the server certificate. This will be done using a new endpoint and with a two year notice.
BreakingYes
We may add new hintCode without prior notice. RP must consider this in their implementation. If RP receives an "unknown" hint code a general message should be presented to the user.
BreakingNo
We may add new errorCode without prior notice. RP must consider this in their implementation. If RP receives an "unknown" error code a general message should be presented to the user.
BreakingNo
We may change the method used to launch the BankID App. This will be done by marking the method as deprecated in this guide and, after two years, eventually release new version of the app that does not support the deprecated method.
BreakingYes
Test environment
New versions and release candidates are used in the test environment prior to roll out in a production environment. Due to this, the content and functionality in the test environment and production environment may temporarily differ.
HTTP/1.1
The service only supports HTTP/1.1. HTTP/1.0 will not work.
TLS versions
appapi2.bankid.com requires TLS1.2 or TLS1.3.