Access Authorisation API specific documentation

Changes from the previous version

This is the changelog of the Access Authorisation API. The topmost item is the latest change and the API changes described in it are relative to the version directly below.

The current latest version of the API is 5.23.

Note: Access Authorisation API version 4 has been deprecated and decommissioned in April 2023. The latest Access Authorisation API is version 5.23

Version 5.23

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.22

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/personal/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/personal/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.21

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.20

BANKIDM_NO for Norway (Mobile BankID Norway) is deprecated and will be removed in the future.

Version 5.19

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.18

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.17

Animated QR code implemented for decoupled authorisation flow for Sweden.

Version 5.16

Consent maximum duration changed to 180 days.

Version 5.15

Decommission Access Authorisation API version 4.

Version 5.14

Code calculator authentication method added for Finland.

Version 5.13

Cancellation endpoint added.

Version 5.12

Decoupled access authorisation flow now also supports Denmark in addition to Finland, Sweden and Norway.

Version 5.11

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

Version 5.10

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

POST personal/v5/authorize

Version 5.9

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

Version 5.8

Decoupled access authorisation flow now also supports Finland in addition to Sweden and Norway.

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

Assets API

GET personal/v4/assets

Redirect Access Authorisation API

GET personal/v4/personal/authorize

POST personal/v4/authorize/token

Token Revocation API

POST personal/v4/authorize/token/revoke

Version 5.7

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

POST personal/v5/authorize

GET personal/v4/authorize

Version 5.6

Decoupled access authorisation flow now also supports Norway in addition to Sweden.

Version 5.5

Assets API is now upgraded to version 5. The API can be accessed via the following endpoint:

• Get user assets - GET /v5/assets

Version 5.4

Decoupled access authorisation flow now supports requesting access to credit card data. To support the new functionality we have added the following:

• account_list parameter now supports a new value ‘ALL_WITH_CARDS’ which enables the TPP to request access to ALL PSU payment accounts AND credit cards.

Version 5.3

Agreement selection introduced in decoupled access authorisation flow. To support the new functionality we have added the following:

• New optional boolean parameter use_primary_agreement in POST /v5/decoupled/authentications
• New endpoint for providing the selected agreement POST /v5/decoupled/authorizations/{agreement_id}

Redirect access authorisation flow now supports requesting access to credit card data when account selection is skipped. To support the new functionality we have added the following:

• account_list parameter now supports a new value ‘ALL_WITH_CARDS’ which enables the TPP to request access to ALL PSU payment accounts AND credit cards.

Version 5.2

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

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

Version 5.1

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

GET personal/v4/authorize

POST personal/v5/authorize

Version 5.0

POST personal/v5/authorize (including also personal/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.3

personal/v4/authorize endpoint: optional login_hint parameter has been removed to avoid personal information in the query string.

Version 4.2

personal/v4/authorize endpoint now supports Sweden in addition to the already supported countries: Finland, Denmark, and Norway. This endpoint also now supports more authentication methods across the four countries.

authentication methods before 4.2:

• NEMID_2F (DK only: NemID with username, password, and OTC/NMAS)
• BANKID_NO (NO only: BankID Norway)
• BANKIDM_NO (NO only: Mobile BankID Norway)

authentication methods added in 4.2:

• MTA_NO (NO only: CodeAppNO - Online)
• BANKID_SE (SE only: BankID Sweden)
• CARD_RDR (SE only: Card Reader e-code)
• MTA (FI only: CodeAppFI - Online)
• MTA_OFF (FI only: CodeAppFI - Offline)
• CCALC (FI only: Code Calculator)

Version 4.1

Changes in the API paths. Endpoints changed to distinguish ‘personal’ from ‘business’ and ‘corporate’ customers.

This has been done by adding a ‘personal’ prefix to the path. For example: /personal/v4/authorize

Version 4.0

KEY CHANGE: QSealC support for ALL authorisation, AIS, and PIS endpoints (exception: /v4/authorize).

Removal of Sandbox-only accounts and new optional account_list functionality:

• /v4/authorize

Removal of unnecessary redirect_uri parameter:

• /v4/authorize-decoupled

Introduction of a new endpoint, enabling TPPs to revoke access (or refresh) token, for example when access authorisation has been withdrawn by the PSU:

• /v4/authorize/token/revoke

Version 3.3

Note: Terminology was clarified in this version: ‘Identity & Access’ and ‘I&A’ were changed to ‘Access Authorisation’.

Support for Refresh Token was introduced in the following endpoints:

• /v3/authorize/token
• /v3/authorize-decoupled/token

Support for Norway was added to access authorisation endpoints:

• /v3/authorize

Version 3.2

Some improvements were made to the Swagger definitions.

Version 3.1

Some improvements were made to the Swagger definitions.

Version 3.0

Redirect access authorisation flow was introduced to support Denmark as well as Finland (note: v2 supports Finland only):

• /v3/authorize
• /v3/authorize/access/token

Version 3 of Access Authorisation API endpoints for Sweden were made available:

• /v3/authorize-decoupled
• /v3/authorize-decoupled/<session_id>
• /v3/authorize-decoupled/token

Version 2.3

Access authorisation endpoints and workflow for Finland were changed. Endpoints for Finland are the following:

• /v2/authorize
• /v2/authorize/access_token

Access authorisation endpoints and flow for Sweden were added. Endpoints for Sweden are the following:

• /v2/authorize-decoupled
• /v2/authorize-decoupled/token

Refresh token functionality is not available for v2

Version 2.2

Many data items that had availability status Beta are now Stable.

Version 2.1

The following changes were made to the response message data items:

• Response message data items have been renamed, this will only impact to TPPs who generate code directly from the swagger definition.
• ExternalError replaces ErrorResponse
• ExternalFailure replaces Failure
• ExternalRequestEcho replaces ApiRequestEcho. The error element under it has been renamed to response.

Version 2.0

• Swagger file is now available for developers
• Consent granting process is now improved
• Improvements for existing APIs
• Access Authorisation API has gone through major changes and the new version is not compatible with the old version. See Access Authorisation documentation, especially the quickstart guide to see how to use the new version.
• Generally the new version is not compatible with the old version, so the applications built using version 1 of the API have to be updated.

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 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, before 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 these steps:

Redirect access authorisation flow:

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.

Decoupled access authorisation flow:

1. Initiation of customer authentication
2. Polling of the authentication status
3. Receipt of the first authorisation code
4. Initiation of the access authorisation
5. Receipt of the second authorisation code
6. Exchange of the second 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 access authorisation flow:

Redirect access authorisation flow

• For Denmark, Finland, Norway and Sweden: POST /authorize endpoints

Decoupled access authorisation flow

• For Denmark, Finland, Norway and Sweden: POST /decoupled/authentications & POST /decoupled/authorizations

The authorisation code:

Redirect access authorisation flow

• For Denmark, Finland, Norway and Sweden: 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.

Decoupled access authorisation flow

• For Denmark, Finland, Norway and Sweden: received by polling the GET /decoupled/authentications/{session_id} endpoint with the session ID. First authorisation code will be received when the resource owner authenticates themselves. This first authorisation code will then be used in a following request to POST /decoupled/authorizations endpoint. This request results in a second authorisation code that can finally be exchanged for an access token.

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):

Redirect access authorisation flow:

• For Denmark, Finland, Norway and Sweden: via POST /authorize/token

Decoupled access authorisation flow:

• For Denmark, Finland, Norway and Sweden: via POST /decoupled/token

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 and Sweden:

Decoupled access authorisation flow

For Denmark, Finland, Norway and Sweden:

Sweden and Denmark 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, currently available in Finland, Sweden, Denmark, and Norway, 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: Before initiating this flow, it is assumed the client will have negotiated consent with the resource owner.

Note: When skip_account_selection in POST personal/v5/authorize is set to “true”, then access to PSU card information can be requested by providing value “ALL_WITH_CARDS” in account_list. With this value present, TPP can request access to all of the PSU’s accounts AND credit cards.

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 if requested by the TPP, to select accounts for which the agreed access should apply.

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 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 the duration this access has been agreed.
2. The client calls Nordea’s /authorize endpoint, passing, amongst other mandatory and optional parameters, the agreed access scopes and duration.
3. Nordea responds with an acknowledgment.
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. 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 accounts(s) were already provided in the /authorize call), and clicks ‘Continue’.
6. Whilst the resource owner is being redirected back to the client’s application, Nordea responds to the client through the redirect URI with an OAuth2-style auth code.
7. 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.
8. 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 /personal/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 /personal/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 the client ID and secret are always sent, in every single authorisation, AIS, and PIS request.

Here is an example of 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 that 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 to acquire an access token and a refresh token.

To receive an access token, the client (TPP application) and resource owner (customer) must first agree on 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 reviews requested access, selects accounts, and authorises access.
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 on consent with the client, and then the client starts the process by initiating the redirect authorisation access 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 refer to the Swagger definition to find optional parameters that you can add to the request, and for the different values of these parameters.

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

See the Access Authorisation API specific documentation for example how the OAuth flow works, it can be used through the API console or programmatically.

To clarify the value and meaning of parameters please see API Reference.

Redirect - Receiving the auth code

Once the resource owner has authorised the requested access, the Nordea authorisation server will send an OAuth2-style auth code through the redirect_uri provided in the /authorize request. The state parameter will also be returned together with the auth code.

GET /test.com?code=<code>&state=<state>

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 the 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 and 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 endpoint, 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 then 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. Sweden and Denmark 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. Sweden and Denmark 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 for an 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 should be able to select and authorize the agreement, either for their primary account agreement, and/or for any additional PoA (Power of Attorney) agreements that they may have.

The TPP will call the agreement selection POST /authorizations/{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 or multiple agreements and call request has ‘use_primary_agreement = true’

• Result - Primary agreement is authorised and confirmation is sent

  Note: Parameter ‘use_primary_agreement’ is not relevant for Denmark. In case the resource owner has more than one agreement always one of them must be selected.

1. Use Case 2 - Customer has one agreement and call request has ‘use_primary_agreement = false’

• Result - Primary agreement is authorised and confirmation is sent

1. Use Case 3 - Customer has multiple agreements and call request has ‘use_primary_agreement = false’

• 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, with the call request as ‘use_primary_agreement = false’, 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 = 199711282849
• psu_id = 4301481

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 access 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 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": "194008010011", // optional for SE, DK and NO, mandatory for FI
"response_type": "code",
"use_primary_agreement": true, // optional for SE, default value = true
} 

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 returned for SE
"verify_after": 2000,
}

There is possibility to cancel session in case of some obstacles. To cancel session, the client polls the following endpoint:

DELETE /decoupled/authentications/{session_id} 

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 following response will be returned: 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 (animated QR code). To get the 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 confirms 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 the following cases;

• use_primary_agreement is set to true OR
• use_primary_agreement is set to false but the customer has 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)
}

409 returned for Sweden and Denmark only

The call will return an HTTP 409 with the following response body in the following cases;

• use_primary_agreement is set to false and customer is having multiple agreements

{
  "agreements": [
    {
      "id": "1234567890",
      "type": "Internetbanken Företag",
      "customer_name": "JOHN DOE"
    },
    {
      "id": "1234567890",
      "type": "Internetbanken Företag",
      "customer_name": "JOHN DOE"
    }
  ]
}

Agreement Selection step (For Sweden and Denmark only)

POST /authorizations/{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 expire in field shows the time in seconds for how long the access token is valid.