Authorization API is used in PSD2 APIs as well as in Premium APIs.
Our APIs use the OAuth 2.0 protocol for authentication and authorization. The bank supports common OAuth 2.0 scenarios such as those for web server, single page and mobile applications.
Our documentation covers the Authorization API jointly for different user flows. In order to implement Authorization API correctly, you should also check the RFCs connected to the Authorization API, mainly:
To begin, obtain OAuth 2.0 client credentials from the Developer Portal. Then your client application requests an access token from the bank Authorization Server, extracts a token from the response, and sends the token to the banking API that you want to access.
Please note that Proof Key for Code Exchange (the pair compound of code verifier and code challenge) are required only if the grant type is equal to authorization code (in the flows, where you have to user GET/authorize call)
Our APIs support following grant types:
Authorization Code Grant, which is used in:
- Accounts API
- Payments API (payment submission)
- Premium API
Client Credentials Grant, which is used in:
- Payments API (payment initiation)
- Funds API
Scope differs according to the API resources, which you want to call. Our APIs support following scopes:
- AISP (to access Accounts API)
- PISP (to access payment initiation in Payments API)
- payments (to access payment submission in Payments API)
- PIISP (to access Funds API)
- PREMIUM_AIS (to access Premium API)
All applications follow a basic pattern when accessing a banking API using OAuth 2.0. At a high level, you follow four steps:
Step 1. Obtain credentials
Register your application on the Developer Portal to obtain OAuth 2.0 credentials such as a client ID and client secret that are known to both the bank and your application. To register your application visit Applications page from your dashboard and click to button Add Application. Provide application information and select APIs that will be accessed by your application. After saving the application settings OAuth 2.0 client credentials are generated and you can access them in the Auth section of your application.
Step 2. Obtain an access token
Before your application can access private data using a banking API, it must obtain an access token that grants access to the API. A single access token can grant various degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that access token permits. During the access-token request, your application sends one or more values in the scope parameter.
Some requests require an authentication step where the user logs in with their bank account. After logging in, the user is asked whether he/she is willing to grant the permissions that your application is requesting. This process is called user consent.
If the user grants the permission, the bank Authorization Server sends the access token to your application (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error.
Step 3. Send the access token to the API
After the application obtains an access token, it sends the token to a bank API in an HTTP authorization header. It is possible to send tokens as URI query-string parameters, but we do not recommend it, because URI parameters can end up in log files that are not completely secure. Also, it is good REST practice to avoid creating unnecessary URI parameter names.
Access tokens are valid only for the set of operations and resources described in the scope of the token request. For example, if the access token is issued for the Account Information API, it does not grant access to the Payment Initiation API. You can, however, send that access token to the Account Information API multiple times for similar operations.
Step 4. Refresh the access token, if necessary.
Access tokens have limited lifetime. If your application needs an access to the banking API beyond the lifetime of a single access token, it can obtain a new access token by using a refresh token. The refresh token allows your application to obtain new access token. Tokens might be issued by two different grant types: Client credentials grant and Authorization code grant.
Client Credentials Grant
When the access token issued through a Client Credentials Grant expires, you must get a new access token by executing a client credentials grant again.
Authorization Code Grant
Due to the immediate nature of single immediate payments, the access token is unlikely to expire before it is used for creating the payment-submission. Consequently, issuing a refresh token along with the access token is not useful in this situation. However, to simplify the implementation, the bank may issue a refresh token along with an access token at the end of the authorization code grant. When the access token obtained through the authorization code grant expires, you may attempt to get a new access and refresh token as defined in Section 6 of the OAuth 2.0 specification. If you fail to get the access token using the refresh token, you would have to get the bank client to initiate new authorization code grant.