API authorization and authentication

By definition, certain critical PSD2 APIs require OAuth2 authentication. These APIs are clearly marked in our API documentation and Swagger definitions. OAuth2 is required in both the simulation and production environments.

Examples of APIs requiring OAuth2:

• Consent APIs (all within the PSD2 Account Information product)

• Payment APIs (e.g., payment initiation requests)

In addition, these APIs typically require a Strong Customer Authentication (SCA) step—unless an exemption is defined by business rules. The SCA process is necessary to comply with regulatory requirements and ensure secure access and transaction authorization.

We use the OAuth2 Authorization Code Flow for securing access to protected APIs.

To begin, open the GET /oauth/authorize URL in a browser with the following parameters: response_type, client_id, redirect_uri, scope, iban(optional).

Scope Values:

• For Account Information: psd2:acc

• For Payment Initiation: psd2:pay

Example:

https://api-oauth.bankart.si/psd2/gbkr/oauth/authorize?response_type=code&client_id=db...&redirect_uri=https://www.xyztpp.si&scope=psd2:acc&iban=SI56XXXXXXXXXXXXXXX

Be sure to use your own application's client_id and redirect_uri (registered during app creation).

When the authorization page opens, enter the username and password, on the second screen, click "Allow Access". You will then be redirected to your redirect_uri with an authorization code included as a URL parameter. Extract this code value — you'll need it to get your access token.

To exchange the authorization code for an access token, you’ll need a tool that can perform a POST request (e.g., curl). You need to pass grant_type, client_id and code as x-www-form-urlencoded data.

Example:

curl -d "grant_type=authorization_code&client_id=dbe...&code=AAL7lhdq6k..." \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "accept:application/json" \
     -X POST https://api.bankart.si/psd2/gbkr/oauth/token

This will return a JSON object containing the access token. You can now use this token to call OAuth2-protected APIs. Add the token in the Authorization header of your requests, prefixed with Bearer. Alternatively, you can paste the token into the "Access token" field in the developer portal to call the API directly from there.

Note: The access token is valid for 5 minutes. 

For more information on endpoints, parameters, and response formats, refer to the published Swagger API documentation.

According to the PSD2 Berlin Group standard, a Strong Customer Authentication (SCA) step is required after certain crucial (i.e., sensitive) API calls, such as:

• Create Consent

• Read transaction lists (to retrieve transactions older than 90 days)*

For this, we use an implicit flow with a simple redirect (no OAuth2). Please check the API response header for the ASPSP/PISP-SCA-Approach value. When present, redirect the end user to the URL provided in the _links/scaRedirect response element.

There is no direct return of information from this redirect to your application, but certain crucial calls are made in the background to complete the authorization and process the payment or create the consent object.

You can verify the outcome of the SCA process using the corresponding API call: GET /consents/{consentId}/authorisations/{authorisationId}. For more details, see the API documentation or Swagger definition.

* Note on transaction list access:
Calls to read transaction lists are limited to a 90-day period from the time of the request. However, during the first 5 minutes of an AIS consent lifecycle, any GET /transactions request will not be subject to this limit. After this initial period, the 90-day restriction applies, and requests for transactions older than 90 days will be rejected.