Developer documentation
The purpose of this documentation is to give an overview of the Application Manager Access Authorisation API which allows Third Party Providers (the client) to authorise itself for the purpose of use the Application Manager API.
This API implementation is Representational State Transfer Service (RESTful service in short), and the responses produced by the Nordea API are in JavaScript Object Notation, JSON format. The API also consumes JSON so requests sent to it should have the request body in JSON format.
Note that this API might change in the future based on feedback. Backward compatibility is not guaranteed. This document discusses the latest version of the APIs.
The current version of the API is 1.0.
API overview
The Application Manager Access Authorisation API enables the client to initiate authorisation access and retrieve access token, that can be used in Application Manager API only.
Getting an access to API
No additional onboarding is needed and you can start testing your workflow right away. When you are ready to migrate your solution into production you should use your credential that were received during onboarding.
Application Manager Access Authorisation API endpoints
The following endpoint supports Application Manager Access Authorisation API.
| Endpoint | Supported HTTP method | Description |
|---|---|---|
| /authorize/token | POST | Provide username and password to get access token for further use |
Terminology
In this section, to avoid confusion, we go through some terminology used in the documentation.
| Term | Explanation |
|---|---|
| API Call | API call is a request towards the API which receives a response. The API is by design stateless, and therefore it does not “remember” anything about previous requests, i.e., there is no session. Therefore every request made towards the API must contain certain headers so that the API can authenticate and authorise the client. |
| Client | The client refers to the consumer of the API. |
| Sandbox | Sandbox in the context of this API means a mocked service whereby the data returned by the API consists of example data. Its purpose is to mimic the current production and upcoming versions of the API. The Sandbox API will always have the latest version of the API, meaning that all new versions appear in the Sandbox before they are introduced into the production. Developers can create their account and transaction data for use in the Sandbox environment. |
| Third Party Provider (TPP) | Third-Party Provider (TPP) is the provider of one or more applications which the resource owner (customer) uses. TPP is the client/consumer of the API. |
| Token | A token which is retrieved by the client after successful response from /authorize/token endpoint. The token is passed by the client in all Application Manager API calls. Note: token retrieved via Application Manager API cannot be used for other API calls like AIS, PIS. |
API HTTP methods
RESTful APIs like this one use HTTP methods to perform actions to fetch, modify, add, or delete resources. Here we list methods used by this API.
- POST - This method creates a new resource. It returns 201 on success.
Client authentication
The username and password that is used to logon to the API Market is sufficient credential to manage TPPs’ applications data. The token that is returned after successful authentication at /authorize/token/ endpoint can only be used for Application Manager API. It cannot be used for other API calls like AIS, PIS.
API swagger definition
The Application Manager Access Authorisation API specification is also available in the Swagger format. Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification (OAS). More information about it can be found here.
API versioning
The API is versioned by the version number in the URL, for example, if the URL is:
https://open.nordea.com/v1/some/api/endpoint
Then the version of the API and endpoint in question is version 1 (v1). When new versions are released, the version numbering will be incremented, that means, next version will have the following URL:
https://open.nordea.com/v2/some/api/endpoint
How it works?
Prerequisites
To be able to use and consume Application Manager API there are few requirements:
- Application has to be created.
- User login and password are required.
Application is created during onboarding process, as well as user login and password.
The registration to the API Market
The registration to the API Market is described in Help Centre link
Application Manager Access Authorisation API description
Token request
The username and password are generated during onboarding to Nordea Open Banking. Here is the example of how the parameters look in the request towards POST v1/authorize/token:
{
"username": "string",
"password": "string"
}
With correct username and password the API should return the following response:
"access_token": "ggt2VaEtxKnrBOLgZAHR6BktnEKtUpCnVTfm8e0Z6-fZM7zDeMT1zcMb4TnAeLkuhPfS(…)",
"token_type": "Bearer",
"expires_in": 28800
Error codes and responses
Every response returned by this API has a response code. Response codes can be used to check the result of the requests, e.g., was the request successful or did it fail.
The following table shows the return codes used by Application Manager Access Authorisation API:
| HTTP Status Code | Text | Description |
|---|---|---|
| 201 | Created | The request has been fulfilled, resulting in the creation of a new resource. |
| 400 | Authorisation failed | Bad request - authorisation failed. |
| 401 | Unauthorised | Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
| 403 | Forbidden | |
| 404 | Not Found | The requested resource could not be found but may be available in the future. |
| 500 | Internal server error |
The difference between the upcoming production API and Sandbox API
The production version of the API provides access to real customer data. For example, you will be able to get a real application and certificate information. The Sandbox is the environment where the application developers can develop their applications before they are promoted to production. The Sandbox API is a superset of the production API, and there will be ‘Sandbox-only’ features in the Sandbox which are never going to be in the production version of the API. The Sandbox and production APIs might have beta features that are subject to change in the future because they are developed based on the feedback. These beta features are included so the developers can already test them and give feedback regarding them. The beta features are marked as a beta in the API reference which can be found at the bottom of this page.
How to test on Sandbox
There are several prerequisites to be able to test Application Manager API:
- You have to be registered to API Market Sandbox link.
- Application has to be created with username and password provided.
While calling POST v1/authorize/token endpoint use username and password that you created during registering to API Market.
Common issues
In this section, we will collect the common issues that the users of the API face. This section will be updated over time.