Developer documentation

The purpose of this documentation is to give an overview of the Application Manager API which allows Third Party Providers in the first phase to manage their applications certificate.

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 API enables the client to retrieve basic information about its’ applications and manage certificate that is linked to client’s applications.

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 API endpoints

There are several endpoints that support Application Manager API.

Terminology

In this section, to avoid confusion, we go through some terminology used in the documentation.

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.

• GET - This method reads a resource and returns it. It returns 200 on success.
• POST - This method creates a new resource. It returns 201 on success.
• PATCH - This method requests that the entity provided is stored in the URI provided. It returns 200 on success.
• DELETE - This method deletes the resource identified by URI. It returns 204 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 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.
• With username and password access token is generated.

Application is created during onboarding process, as well as username and password.

There are the following steps that need to be done before using APIs to manage applications:

1. Access token needs to be generated.
2. Organization id needs to be retrieved unless it is already known.
3. Application id needs to be retrieved unless it is already known.

The following diagram illustrates how the flow works, where there are the following parties:

• Client is TPP, owner of the Client Application consuming Nordea’s Open Banking API.
• Nordea Open Banking (API).

1. The client calls /authorize/token endpoint with username and password to get access token.
2. Nordea responds with access token.
3. The client calls GET /orgs endpoint to get list of it’s organizations. If the client already knows organization id this step can be skipped.
4. Nordea responds with the list of organization ids.
5. The client selects organization id and with this id calls GET /orgs/{organization_id}/apps endpoint. If the client already knows application id this step can be skipped.
6. Nordea returns list of application ids.
7. The client selects application id for which the following actions can be done: GET certificate data, POST to add certificate to the application, PUT to replace certificate with the new one or DELETE to deactivate certificate.

The registration to the API Market

The registration to the API Market is described in Help Centre link

Application Manager API description

Request to get organizations list

Here is an example of how the parameters look in the request header towards GET /orgs endpoint:

...
other Header data omitted
...
Authorization: Bearer <ACCESS-TOKEN>
...
other Header data omitted
...

The response with the list of organizations will look like in the following sample:

  "group_header": {
    "creation_date_time": "2023-12-22T10:50:18.825Z",
    "http_code": 200,
    "message_identification": "string"
  },
  "response": {
    "organizations": [
      {
        "created": "string",
        "id": "123456789",
        "name": "Best TPP",
        "status": "ENABLED",
        "updated": "string"
      }
    ]
  }
}

Request for applications list

The client calls GET /orgs/{organization_id}/apps endpoint to get list of applications for given organization_id.

The response with the list of applications will look like in the following sample:

{
  "group_header": {
    "creation_date_time": "2023-12-22T11:25:16.826Z",
    "http_code": 200,
    "message_identification": "string"
  },
  "response": {
    "applications": [
      {
        "created": "string",
        "id": "string",
        "org_id": "string",
        "status": "ENABLED",
        "title": "string",
        "updated": "string"
      }
    ]
  }
}

Get certificate request

For given organization_id and application_id the client can now get certificate information calling the following endpoint:

GET /orgs/{organization_id}/{application_id}/certificates/

The response body should look like in the following sample:

"response": {
    "certificates": [
	{
		"app_id": "string",
		"certificate": "<certificate>", 
		"status": "active",
		"expires_in": 300,
		"id": "string"
	}
   ]
  }

Add or replace certificate request

To add certificate to given application the client should use the following endpoint:

POST /orgs/{organization_id}/{application_id}/certificates/

or the following one to replace certificate:

PATCH /orgs/{organization_id}/{application_id}/certificates/

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

state=123
 &organization_id=123456789
 &application_id=123456789
 &certificate=<your-certificate>

The response with status 201 OK will look like in the following sample of body:

{
 "app_id": "string",
 "certificate": "<certificate>", 
 "status": "active",
 "id": "string",
 "expires_in": 300
 }

Delete certificate request

In order to delete certificate for given application the client should call the following endpoint:

DELETE /orgs/{organization_id}/{application_id}/certificates/

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

state=123
 &organization_id=123456789
 &application_id=123456789

The response will return status 204 OK.

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

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 in 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.
• Access token is generated after successful authorisation (result of POST v1/authorize/token request).

Using access token generated in Application Manager Access Authorisation flow you can then manage certificate that is linked to application you created in API Market Sandbox.

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.