Access Token - Version 1

To interact with the Open Banking Service securely, you need to retrieve an access token.

This is done by a POST /token call via the Authorization API.

STEP 1 - Upload certificate

Before making the Authorization request, you will first need to upload your public certificate under a specific subscription in our back office portal. You will get access to the back office portal as part of setting your test environment phase.
The certificate can be self signed and should adhere to the following requirements:

minimum leftover validity: more than 1 month
maximum validity: 5 years
key size/length: minimal length 2048, maximum length : 4096
algorithm: SHA - 256 with RSA

STEP 2 - Retrieve an access token via the Authorization API

Endpoint : POST /token
Base URL: /xs2a/routingservice/services/authorize

To request an access token, you must digitally sign the relevant request headers using the private key associated with the certificate that you have uploaded to the back office portal.

Steps on signing the Authorization requests are available within the section Digital Signatures - Sending authorization requests. You should follow the guidelines in order to properly sign the Authorization requests.

Important Fields for creating API call for Authorization API

Request

Header fields	Type	Description
Content-Type required	String	To identify the media type of the source. If not provided, the Initiating Party can expect to come across the error "415, Unsupported Media Type".
Authorization required	String	The signature. It contains the header attributes 'app', 'client', 'id' and 'date' signed with the private key of the client. The signature will be used to sign the authorization request with the private key which corresponds to the certificate provided during the onboarding. Structure `Signature keyId=”<thumbprint of certificate>”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”<signature>”` Example `Signature keyId=”58AF4EC5ADD4C4A3F28D3AEFF60656B2F2xxxxxx”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”Abczym2rZF…r5qcvgmA==”` Refer to the chapter Digital Signatures - Sending authorization requests for more information
App required	String	The name of the service. Only PIS, IDEAL or AIS is allowed.
Client required	String	The name of the client. This name is provided to the Initiating Party during onboarding. The name of the client is created by the Open Banking Service and will be provided to you.
Id required	String	The combination of Initiating Party ID and sub Id separated by semi column. In case there is no sub id, no semi column should be provided. You can find these IDs in the back office portal. Example: IP=433, subId=5 -> the ID will be 433:5. IP=434, no subId -> the ID will be 434.
Date required	Date	Should be filled with the current date. The following date formats are supported: 1. EEE MMM dd HH:mm:ss zzz yyyy 2. ISO DATE: for example 2011-12-03T10:15:30+01:00 3. RFC 1123: for example Tue, 3 Jun 2008 11:05:30 GMT

Form Data	Mult.	Type	Description
grant_type	1..1	String	To be set to ‘client_credentials’

Response

Body fields	Mult.	Type	Description
access_token	1..1	String	Token to be used in further API calls
token_type	1..1	String	Type of the token: Bearer
expires_in	1..1	Integer	Expiration time in seconds.

Upon a successful request, the Open Banking Service provides you with an access token, which must be used in all future API interactions, such as POST /payments or GET /preferences, etc. This token should be included in the Authorization header of subsequent requests as follows:

Authorization:Bearer 4944daeae6c9115a10dafecbfad4a9c

This access token allows the Open Banking Service to validate and authorize your API requests.

Example: Authorization

Request

Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/authorize/token?grant_type=client_credentials
HttpMethod: POST
Headers: {App=IDEAL, Accept=application/json, Date=2024-02-08T18:31:37.548Z, Authorization=Signature KeyID="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f", algorithm="SHA256withRSA", headers="app client id date", signature= "r0EqeVMfc4au9fq7ZVhOwjfXbMHkf2GShAH/WIQtjMyjl2swlJss10Y0Fjpqt47aLdeBXpG28mVxzPLjwqNHPvnkNPslepJmHzB3W2A6YgXcoiUqFFv+pxzIBmohVoqVEGb5QC4rxTBpAleE178hSzIJrxxbhlCQv/dSAcoI5V1P1M3pU9VqM7vmql8XlB/yXOjmayeXVtB0T93BzqutHokHBwDjxN8ocKlsX40GcFoFjxov9cKoVjlyMZKyfHRkqZ5u1dUkcN+RFeGgJWCcCcaBydXSicK/elbpq55rAgLCTQF4xFldSDPjcrRsswMIYMZmGz0tCycjDV225pGPGg==", content-type=application/x-www-form-urlencoded, Id=000081, Client=Worldline}

Response

ResponseCode: 200
Headers: {X-Request-ID=2aa0dc88-21dd-4034-a027-1d98123596f1, MessageCreateDateTime=2024-02-08T18:31:38.385Z, Date=Thu, 08 Feb 2024 18:31:38 GMT, Content-Type=application/json;charset=UTF-8}
Payload: {
"access_token": "bb00ffd85e0b619a7a9da34df24346f8b309dae54383e5e5481bada22aaa000e",
"token_type": "Bearer",
"expires_in": 3600

Validity of access tokens

As a default, tokens are valid for 60 minutes (3600 seconds). After 60 minutes have elapsed, you will need to request for a new token.
There is an overlap period in the last 10 minutes (between 50th minute - 60th minute). This means if you were to request a new token between 50th minute to 60th minute, you would receive a new access token.

However, for those 10 minutes, the previous token would also still be valid.