Access authorisation API specific documentation

Changes from the previous version

The top most item is the latest change and the API changes described in it are relative to the version directly below. The current version of the API is 5.18.

Note: Business Access Authorisation API version 4 has been deprecated and decommissioned in April 2023.

Version 5.18

User id less login feature implemented for Norway decoupled access authorisation flow. Parameter ‘psu_id’ is not mandatory for Norway any longer. Decommission of code calculator authentication method in Finland.

Version 5.17

As a consequence of upgrading the Swedish BankID application from v1 to v2, there will be slight change to the authentication services, particularly to the decoupled flow.

In the GET https://api.nordeaopenbanking.com/business/v5/decoupled/authentications/{session_id} endpoint we will stop sending qr code parameter in the response, immediately after it has been scanned by the user.

We will continue to send the qr_data parameter in the POST https://api.nordeaopenbanking.com/business/v5/decoupled/authentications endpoint.

The qr_data has always been marked as an optional parameter in the swagger documentation, so this should not cause any disturbances.

Version 5.16

Three below mentioned deprecated methods have been finally decommissioned:

• Nordea ID authentication method in offline mode (MTA_OFF)
• Mobile BankID for Norway (BANKIDM_NO)
• QR reader for Sweden (QR_RDR)

Version 5.15

BANKIDM_NO for Norway (Mobile BankID Norway) is deprecated and will be removed in the future. MTA_NO authentication method added for Norway decoupled flow.

Version 5.14

Nordea ID authentication method in offline mode (MTA_OFF) that has been available in the redirect authorisation flow in Finland will be decommissioned in May 2024.

Version 5.13

New scope: “PAYMENTS_SINGLE_SCA” added as a supported parameter in POST/v5/authorize endpoint. It’s a backup solution for cancelling of single SCA payments. In case, the auth_code will not get exchanged for the access token during the SCA payment, there is a possibility to call external autorisation endpoint POST/v5/authorize and get the new auth_code that can be later exchanged for the access token with the “PAYMENTS_SINGLE_SCA” scope. More information about this parameter can be found below in swagger definition files and Payments API Single SCA

Version 5.12

Animated QR code implemented for decoupled authorisation flow for Sweden.

Version 5.11

Consent maximum duration changed to 180 days.

Version 5.10

Decommission of Access Authorisation API version 4.

Version 5.9

Code calculator authentication method added for Finland.

Version 5.8

Decoupled Access Authorisation flow now also supports Denmark in addition to Finland and Sweden.

Version 5.7

MTA_DK (Nordea ID login) added as a supported value in authentication_method parameter in Denmark.

POST business/v5/authorize

Version 5.6

account_list parameter now supports requesting access to specific currency variant of a multi-currency payment account. More information can be found in API Reference section, under following endpoints:

POST business/v5/authorize

POST business/v5/decoupled/authorizations

MTA_QR (Nordea ID QR code login) added as a supported value in authentication_method parameter in Finland.

POST business/v5/authorize

Version 5.5

Decoupled Access Authorisation flow now also supports Finland in addition to Sweden.

Nordea Codes app rebranded to Nordea ID. Terminology aligned across our documentation.

Version 5.4

company_id input parameter has been made optional across the following APIs and endpoints:

Redirect Access Authorisation API:

GET business/v4/authorize

POST business/v5/authorize

Decoupled Access Authorisation API:

POST business/v5/decoupled/authentications

Business Access Authorisation API version 4 with the following endpoints has been deprecated, and will be decommissioned in May 2022:

Assets API

GET business/v4/assets

Redirect Access Authorisation API

GET business/v4/personalauthorize

POST business/v4/authorize/token

Token Revocation API

POST business/v4/authorize/token/revoke

Version 5.3

MitID (MitID for DK) added as a supported value in authentication_method parameter for Denmark in the following endpoint:

POST business/v5/authorize

GET business/v4/authorize

Version 5.2

New field customer_id added in the following endpoint:

• POST business/v5/decoupled/authorizations HTTP 409 response with agreement list

Version 5.1

Decoupled access authorisation flow introduced for Sweden. With the new flow we have exposed the following endpoints.

• Authenticate call - POST business/v5/decoupled/authentications
• Authentication status call - GET business/v5/decoupled/authentications/{session_id}
• Authorisation call - POST business/v5/decoupled/authorizations
• Token exchange - POST business/v5/decoupled/token

Version 5.0

POST business/v5/authorize (including also business/v5/authorize/token) introduced across four countries supporting an option to skip the account selection step during the Access authorisation flow. This is enabled by introducing a new optional parameter skip_account_selection.

Version 4.4

QR_RDR (QR Reader for SE) added as a supported value in authentication_method parameter for Sweden in the following endpoint:

GET business/v4/authorize

Version 4.3

Redirect access authorisation flow updated to show Company ID validation

Company ID values for different countries in newly added Company ID in Different Countries section

Version 4.2

New optional item added X-Nordea-Sandbox-Authorizer-Id for user selection - available only in Sandbox.

Different user account access listed in newly added Sample test data section.

Version 4.1

business/v4/authorize endpoint: optional login_hint and psu_id parameters have been removed to avoid personal information in the query string

Version 4.0

Although this is the first version of Nordea Business specific APIs, we have decided to use ‘v4’ to make it clear that the endpoints align closely to the ‘v4’ endpoints for personal customers in terms of interface definition and behavior.

Overview of access authorisation API

Access authorisation API consists of endpoints that enable clients (TPP Applications) to initiate access authorisation flow, whereby the resource owner (Customer) authorises account access. Ultimately the client receives an access token that can be used in AIS and PIS calls as applicable.

Note: According to the Delegated Regulation, which amends the regulatory technical standards (RTS) since 25th July 2023 maximum consent duration will change from 90 to 180 days.

Note: it is assumed that, prior to initiating this flow, the TPP will have negotiated consent with the customer.

Note: the client can also query the /assets endpoint for information on the authorised access (accounts and scopes).

Note: the client also receives a refresh token together with the access token that can be used to obtain a new access token after expiry.

How it works

To be able to use the AIS and PIS APIs, the client needs an access token. The client is provided with an access token after the resource owner has authenticated themselves and authorised access to their accounts.

The access token generation consists of three parts:

1. Initiation of access authorisation.
2. Receipt of an authorisation code.
3. Exchange of the authorisation code for an access token and a refresh token.
   • The refresh token can be used to obtain a new access token after its expiry.

Initiation of the authentication and authorisation flow: /authorize endpoint

The authorisation code is received via the client’s redirect URI. * An authorisation code will be received when the resource owner authorises access and is then redirected back to the client.

Please note that the authorisation code is one time use only and is never used or required again after it is exchanged to access token.

The authorisation code is subsequently exchanged for an access token (and associated refresh token): via authorize/token (POST)

Once an access token has been received, the authentication and authorisation flow is complete.

API endpoints

The Access Authorisation API has the following endpoints:

Redirect Access Authorisation flow

For Denmark, Finland, Norway & Sweden:

Decoupled Access Authorisation flow

For Denmark, Finland, Norway & Sweden:

Sweden only:

We also provide the following additional endpoints for the TPPs.

The endpoint usage is described in more detail below.

Redirect access authorisation flow

The redirect access authorisation flow enables the client to get access to a Nordea resource owner’s payment accounts, subject to the resource owner’s authorisation. The client calls the /authorize endpoint to initiate this flow, from which the customer is directed to authenticate themselves and select accounts if applicable, for which the agreed access should apply. The client can then acquire an access token to use in the AIS and PIS APIs.

Note that, prior to initiating this flow, it is assumed the client will have negotiated consent with the resource owner.

The framework has four roles:

• Resource owner - payment account holder with Nordea.
• Client - TPP, owner of the client application consuming Nordea’s Open Banking API.
• Nordea Open Banking (API).
• Nordea User Interface, enabling the resource owner to authenticate themselves and select accounts (if account selection on bank side is chosen).

The resource owner is the person giving the consent to the client’s application to access their payment account information - and/or to initiate payments on their behalf - for one or more of their payment accounts and for an agreed duration. The client is the owner of the client application which is requesting this access. It is important to stress that the consent is between the client and the resource owner.

The following diagram illustrates how the flow works:

1. Consent is negotiated and agreed between the customer (resource owner) and the TPP (client). Amongst other information that makes up explicit consent, this will include the scope of access required and duration this access has been agreed along with the Company ID to which the resource owner wants to provide consent for.
2. The client calls Nordea’s /authorize endpoint, passing, amongst other mandatory and optional parameters, the agreed access scopes, duration and Company ID.
3. Nordea responds with an acknowledgement.
4. The resource owner is redirected to Nordea, where they authenticate using their Nordea credentials (for example, via Nordea ID in Finland, MitID in Denmark, Mobile BankID in Sweden and BankID in Norway).
5. The resource owner is given the ability to select an agreement which should belong to the company for which access has been requested.(unless the resource owner has access to only 1 agreement)
6. Note: This step is only present if account selection is enabled for the resource owner - the resource owner is shown the access and duration, plus the ability to select the accounts for which this access should apply (unless account(s) were already provided in the /authorize call), and clicks ‘Continue’.
7. Whilst the resource owner is being redirected back to the client’s app, Nordea responds to the client through the redirect uri with an OAuth2-style auth code.
8. The client can exchange this short-lived auth code for an access token (plus associated refresh token), which can be used for the agreed AIS and/or PIS APIs.(An error would occur if the resource owner had picked an agreement that does not belong to the company, access has been requested for).
9. When the access token has expired, a new access token can be obtained by calling /authorize/token using the received refresh token. The refresh token is long living but one-time only use.

Redirect - How the flow looks like for the PSU

This example illustrates a scenario where a Swedish PSU is going through the redirect access authorisation flow and chooses to use their Mobile BankID as an authentication method.

Scenario: PSU user experience without account selection step in Nordea UI.

TPP calls POST /business/v5/authorize endpoint and provides the following optional input parameters in addition to all of the mandatory parameters.

• skip_account_selection
• account_list

1. PSU is redirected to Nordea, to authenticate themselves.
2. In this illustration, the PSU selects Mobile BankID Sweden as an authentication method.

Note: If authentication_method is provided, the method is pre-selected for the PSU.

1. PSU enters their BankID credentials.
2. PSU is redirected briefly back to Nordea UI.

1. PSU receives an indication of successful authentication.
2. PSU is automatically redirected back to the TPP application.

Scenario: PSU user experience with account selection in Nordea UI.

TPP calls POST /business/v5/authorize without providing skip_account_selection.

The flow looks similar as in the above flow with the exception that after the PSU has authenticated,

1. The PSU is redirected to Nordea UI to select the payment accounts they wish to grant access to.
2. After this selection is done, they can continue the flow and return back to TPP application.

Note: authentication_method can be used together with skip_account_selection to further reduce the interaction of the customer in the Nordea User Interface.

Note: authentication_method and account_list parameter can be used to further reduce the interaction of the user in the Nordea User Interface. When passing these parameters both the authentication method and the account selection are pre-filled for the PSU. Please see Swagger’s definition of the interface for more information.

Redirect - Prerequisites

To be able to use and consume AIS and PIS APIs there are few requirements.

• Application has to be created.
• Client ID is required.
• Client secret is required.
• Access token is required.

The client ID and client secret are generated after the application is created on the My apps page. The client ID and client secret can be found when clicking the app icon after the app is created.

When making requests, the client ID, client secret, and access token are sent in a header of each request. Note that both client ID and secret are always sent, in every single authorisation, AIS and PIS request.

Here is an example how the parameters look in the request header:

...
other Header data omitted
...
Authorization: Bearer <ACCESS-TOKEN>
...
other Header data omitted
...
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

If the client secret is lost or leaked, it can be regenerated by clicking the reset button from the apps page. See the examples section of any API to learn how these headers are sent.

Note that the X-IBM-Client -Id and X-IBM-Client -Secret parameters are only used by the client (TPP application). `

Redirect - Access Authorisation API

In the previous section, we described the requirements to connect to the AIS and PIS APIs. The client ID and client secret are parameters which are configured to the TPP, and they are never exposed to the actual application customer. After they are configured, the TPP can initiate the access authorisation flow in order to acquire an access token and a refresh token.

In order to receive an access token, the client (TPP application) and resource owner (customer) must first agree consent, after which the client:

1. The client redirects the customer to Nordea.
2. The resource owner authenticates with Nordea.
3. If account selection is enabled - The resource owner selects accounts - if not already provided in the /authorize request - and clicks ‘Continue’.
4. Nordea redirects the customer back to TPP.

Please note that the auth code and the refresh token are one time use only, codes are never used or required again after they have been exchanged to access token. The refresh token can then be exchanged for a new access token when the existing access token has expired.

After the auth code has been exchanged for an access token, the authorisation flow is complete and the client (TPP application) can start using the API.

Redirect - Initiating the authorisation flow

First, the resource owner needs to agree consent with the client, and then the client starts the process by initiating the redirect authorisation flow. The flow can be initiated through the following endpoints:

POST /authorize

With the URL parameters including those shown in the example below:

/authorize?
state=123
 &client_id=<CLIENT_ID>
 &redirect_uri=https:%2F%2Fexampleuri.org%2Fpost
 &scope=ACCOUNTS_BASIC,ACCOUNTS_BALANCES, ACCOUNTS_DETAILS,ACCOUNTS_TRANSACTIONS,PAYMENTS_MULTIPLE
 &duration=500
 &country=<country code>

…plus additional optional parameters

Please note that some optional enumerations contain values in the Sandbox that are not necessarily released to production all at once. For example, the endpoint is rolled out country by country. Also, authentication methods are rolled out to production at different times.

For more information on the value and meaning of all mandatory and optional parameters, please see API Reference.

The call will return an HTTP 302 redirect code, indicating a successful redirect.

Redirect - Receiving the auth code

Once the resource owner has authorised the requested access, Nordea Authorisation Server will send an OAuth2-style auth code through the redirect_uri provided in the /authorize request. If the state parameter was passed in the request, this will also be returned.

GET /test.com?code=<code>

Redirect - Token exchange

Now that the auth code has been received, it can be exchanged for an access token and a refresh token by calling:

POST  /authorize/token

The Header includes:

...
other Header data omitted
...
-H "X-IBM-Client-Id": <Client ID>
-H "X-IBM-Client-Secret": <Client Secret>
-H "Content-Type": "application/x-www-form-urlencoded"

The example body looks like this:

Requesting an access token with an authorization_code

  code=<CODE>
  &redirect_uri=http://exampleuri.com/post
  &grant_type=authorization_code

Requesting an access token with a refresh_token

  refresh_token=<refresh_token>
  &grant_type=refresh_token

The call will return the following response:

{
 "access_token": "<access token value>"
 "expires_in": 300,
 "token_type": "Bearer"
 "refresh_token": "<refresh token value>"
}

Redirect - Token exchange with refresh token

Now that the refresh token has been received, it can be exchanged for a new access token and a new refresh token.

The response above shows the token type, token expiration time in seconds, actual access token which can be used to make requests and a refresh token which can be used to obtain a new access token after the access token duration has expired. Please also note that the auth code to retrieve the access_token will expire in 60 seconds for security reasons.

Decoupled access authorisation flow (Denmark, Finland, Norway & Sweden)

The decoupled access authorisation flow, currently available in Denmark, Finland, Norway and Sweden enables third party providers (TPPs) to get access to Nordea customer’s payment accounts, subject to the customer’s authorisation. TPP starts the flow by calling the POST /decoupled/authentications endpoint in order to authenticate the customer. After this the TPP continues the flow by calling the POST /decoupled/authorizations thereby authorising access to the TPP application. The TPP can then acquire an access token (and associated refresh token) to use in the AIS and PIS APIs.

Note: Prior to initiating this flow, it is assumed the TPP will have negotiated consent with the customer.

The framework has three roles:

• Customer (resource owner, payment account holder with Nordea)
• TPP application (client)
• Nordea Open Banking (API)

The resource owner is the person giving the consent to the TPP application to access their payment account information - and/or initiate payments on their behalf - for one or more of their payment accounts and for an agreed duration.

The client is the TPP application which is requesting this access.

Nordea Open Banking platform exposes the APIs for Access Authorisation, AIS and PIS.

The following diagram illustrates how the flow works:

The decoupled access authorisation flow follows these steps:

1. Consent is negotiated and agreed between the customer (resource owner) and the TPP (client). Amongst other information that makes up explicit consent, this will include the scope of access required, the accounts and the duration this access has been agreed.
2. The client calls Nordea’s /decoupled/authentications endpoint to initiate the customer authentication.
3. Nordea responds with an acknowledgement containing a session ID.
4. For Sweden a QR code and an auto start token is returned together with session ID. The client displays the QR code for customer to scan with their mobile device. The QR code is changing every 1 second, so the client should start polling the following endpoint: /decoupled/authentications/{session_id} to refresh the QR code. The client can also use the auto start token to open the customer’s native mobile authentication application (Mobile BankID in Sweden). More information about the app switch can be found here: https://support.nordeaopenbanking.com/hc/en-us/articles/360014672740-How-to-switch-app-integration-with-Nordea-e-identification-.
5. For Finland an auto start token is not returned and the client can start the Nordea ID automatically in the customer’s mobile device by calling a scheme URL. More information about the app switch can be found here: https://support.nordeaopenbanking.com/hc/en-us/articles/360014672740-How-to-switch-app-integration-with-Nordea-e-identification-.
6. For Denmark and Norway an auto start token is returned only when psu_id is not provided (user id less login). QR code login needs 2 images for successful authentication. Images will rotate with 1 seconds interval. QR code format is: * nordeamta://qrlogin?sessionid={sessionid} * nordeamta://qrlogin?autostarttoken={Auto-start token}
7. While Nordea initiates the authentication step with the customer, the client begins polling the /decoupled/authentications/{session_id} endpoint, using the session ID provided.
8. Once the resource owner has authenticated themselves, the polling request will succeed and a first auth code will be provided to the client.
9. The client then calls Nordea’s /decoupled/authorizations endpoint to request the access authorisation from the customer.
10. After a successful call, Nordea responds with a second auth code.
11. Denmark and Sweden only In case the customer has multiple agreements to choose from, a list of agreements will be returned with a HTTP 409 response. The agreement selection is carried out based on the number of agreements available for the user (as described in the Agreement Selection section below).
12. Denmark and Sweden only TPP provides the agreement based on customer input to endpoint `/decoupled/authorizations/{agreement_id}. This call then results with response including a second auth code.
13. The client can finally exchange this short-lived auth code for an access token (plus associated refresh token), which can be used for the agreed AIS and/or PIS APIs.

Prerequisites

To be able to use and consume AIS and PIS APIs there are few requirements.

• Application has to be created.
• Client ID is required.
• Client secret is required.
• Access token is required.

The client ID and client secret are generated after the application is created on the My apps page. The client ID and client secret can be found when clicking the app icon after the app is created.

When making requests, the client ID, client secret, and access token are sent in a header of each request. Note that both client ID and secret are always sent, in every single authorisation, AIS and PIS request.

Here is an example how the parameters look in the request header:

...
other Header data omitted
...
Authorization: Bearer <ACCESS-TOKEN>
...
other Header data omitted
...
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

If the client secret is lost or leaked, it can be regenerated by clicking the reset button from the apps page. See the examples section of any API to learn how these headers are sent.

Note that the X-IBM-Client-Id and X-IBM-Client-Secret parameters are only used by the client (TPP application).

Access Authorisation API

In the previous section, we described the requirements to connect to the AIS and PIS APIs. The client ID and client secret are parameters which are configured to the TPP, and they are never exposed to the actual application user. After they are configured, the TPP can initiate the access authorisation flow in order to acquire an access token.

In order to receive an access token, the client (TPP application) and resource owner (customer) must first agree consent, after which the client:

Requests for customer authentication

1. Calls /decoupled/authentications, passing the required parameters and receiving a ‘session ID’ and for Sweden ‘auto_start_token’ and ‘qr_data’. For Denmark and Norway auto start token is returned only when psu_id not provided.
2. Opens customer native mobile authentication app OR displays a QR code for the customer to scan (in case customer is on a different device). For Sweden starts polling for a QR code which changes every 1 second and a first auth code using the session ID.
3. Starts polling for a first auth code using the session ID.
4. Once the polling succeeds, receives a first auth code.

Requests for access authorisation from the customer

1. Calls decoupled/authorizations, passing the required parameters with the first auth code and receives a second auth code
2. Exchanges the second auth code for the access token (plus associated refresh token).

Note: The auth code is one time use only, code is never used or required again after it is exchanged to access token.

After the code is exchanged for an access token, the authorisation flow is complete and the client (TPP application) can start using the APIs.

Note: The refresh token is a one-time use token that can be exchanged for a new access token when the existing access token has expired.

Agreement Selection API (For Denmark and Sweden only)

The resource owner (customer) at this point is required to select and authorise the agreement belonging to the company whose data the TPP is requesting access to.

The TPP will call the agreement selection POST /authorization/{agreement_id} endpoint to receive the details of the agreements that are available for the customer. Based on the call request, and the number of agreements available, the following use cases are possible. (refer to diagram below)

1. Use Case 1 - Customer has one agreement

• Result - Agreement is authorised and confirmation is sent

1. Use Case 2 - Customer has multiple agreements

• Result - List of active agreements is sent to the client (TPP application), and once the customer selects the agreement(s) to be authorised, the confirmation is sent.

Note: The agreement list sent to the client consists of agreement ID, agreement type, and agreement name. The agreement name is an optional field, so if it is not available, then only the agreement ID and agreement type is returned.

How to test in Sandbox

In Sandbox testing, the PSU identification step is omitted. Therefore, when any psu_id is used, it may result in only a single agreement being returned. Therefore, we have created a specific test psu_id to support testing the new agreement selection functionality in Sandbox.

Scenario with multiple agreements returned

• psu_id = 197003289258 (SE)
• psu_id = 8263377 (DK)

Scenario with single agreement returned

• No psu_id provided
• psu_id = any id besides the one above for multiple agreement scenario

Initiating the decoupled authorisation flow

First, the resource owner (customer) needs to give consent, and then the client (TPP application) starts the process by initiating the decoupled authorisation flow. The flow consists of two steps, authentication request and an access authorisation request. The endpoints for both steps are described below.

Please refer to the Swagger definition to find optional parameters that you can add to the request, and for the different values of these parameters.

See the Access Authorisation API Specific documentation for examples how the flow works. It can be used through the API console or programmatically.

Authentication step

POST /decoupled/authentications

With the header including:

...
other Header data omitted
...
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

And body:

{
"authentication_method": "BANKID_SE",
"country": "SE",
"psu_id": "197003289258", // optional for SE, DK and NO, mandatory for FI
"response_type": "code"
} 

The call will return the following:

{
"session_id": "<session id>",
"auto_start_token": "<auto start token>", // Only returned for SE, DK and NO (DK and NO only when psu_id not provided)
"status": "assignment_pending",
"qr_data": "<qr code>",  // Only provided for SE
"verify_after": 2000,
}

Polling for auth code

Note: All actions, described below, are available only with the use of the Mobile BankID application. Only after customer confirms the authentication request through the Mobile BankID, the client will get the successful response for the auth code. The code return may take up to 5 seconds.

To retrieve an access token, an auth code is required as a prerequisite. To get the auth code, the client polls the following endpoint:

GET /decoupled/authentications/{session_id}

Where the session_id is a key from the Initiating call that looks like the following:

9d98ea2a-54ec-44d8-a000-17e1b8131190

While TPP waits for the customer to confirm the authentication request, the response will return: 200

The timeout for the polling is 3 minutes in total. The end user has 30 seconds to scan the QR code, then 2 minutes and 30 seconds to enter their security code. If the customer does not confirm the request within these three minutes, the following response will be returned: 400

For Sweden qr_data changes every 1 second. To get a refreshed QR code the client polls the following endpoint:

GET /decoupled/authentications/{session_id}

and until customer authenticates himself the response looks like this:

{
"session_id": "<session id>",
"auto_start_token": "<auto start token>", // Only returned for SE, DK and NO (DK and NO only when psu_id not provided)
"status": "assignment_pending",
"qr_data": "<qr code>",  // Only returned for SE
"verify_after": 2000,
}

Once customer confirmed the request, the response will return a code. The response looks like this:

{
"session_id": "<session id>",
"status": "completed",
"verify_after": 2000,
"code": "<auth code>" // Note: first auth code is returned only when status completed
}

Authorisation step

POST /decoupled/authorizations

With the header including:

...
other Header data omitted
...
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

And body:

{
"account_list": ["41351300039", "1234567890"],
"code": "<auth code>", // Note: Use the first auth code here
"duration": 129600,
"max_tx_history": 12,
"response_type": "code",
"scope": ["ACCOUNTS_BASIC", "ACCOUNTS_BALANCES"]
} 

The call will return the following in case the customer is having only one agreement:

{
"code": "<auth code>" // Note: This is the second auth code which can be exchanged to access token (see below for Token Exchange)
}

The call will return an HTTP 409 with the following response body in case the customer is having multiple agreements:

{
  "agreements": [
    {
      "id": "1234567890",
      "type": "Internetbanken Företag",
      "customer_name": "JOHN DOE",
      "customer_id": "<customer id>" // Note: Last 4 digits will be masked in case the customer id returned is a personal identifier. Company identifiers will be returned unmasked.
    },
    {
      "id": "1234567890",
      "type": "Internetbanken Företag",
      "customer_name": "JOHN DOE",
      "customer_id": "<customer id>" // Note: Last 4 digits will be masked in case the customer id returned is a personal identifier. Company identifiers will be returned unmasked.
    }
  ]
}

Agreement Selection step

POST /authorization/{agreement_id}

With the header including:

...
other Header data omitted
...
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

And body:

{
"code": "<auth code>" // Note: Use the first auth code here
}

The call will return the following:

{
"code": "<auth code>" // Note: This is the second auth code which can be exchanged to access token (see below for Token Exchange)
}

Token exchange

Now that we have the second auth code after a successful authorisation request we can retrieve the access token (plus associated refresh token), plug the code into the URL below that you got from the previous request:

POST /decoupled/token

With the headers including:

...
other Header data omitted
...
Content-Type:application/x-www-form-urlencoded
X-IBM-Client-Id: <Client ID>
X-IBM-Client-Secret: <Client Secret>

Example of the request body using authorisation code:

code=<auth code> // Note: Use the second auth code here
&grant_type=authorization_code

Example request body using refresh token:

refresh_token=<refresh token>
&grant_type=refresh_token

The call will return the following response:

{
"token_type": "Bearer",
"access_token": "<access token>",
"expires_in": 3600,
"refresh_token": "<refresh token>"
}

Token exchange with refresh token

The response above shows the token type, token expiration time in seconds and the actual access token which can be used to make requests. Please also note that the code to retrieve the access_token will expire in 60 seconds for security reasons. Please note that the expires_in field shows the time in seconds for how long the access token is valid.

Company ID Value in Different Countries

Company relationship with Agreement and User

Sample test data