Registration

How to register your redirect URIs and gain access to our Open Banking APIs

👍

Do it now!

Use the API Test Client to directly perform this registration process in the Sandbox Environment

1. Obtain a test certificate

The API Test Client can be used to generate a test certificate that can be used in the Sandbox Environment.

In the Production Environment you can skip this step; instead you will use your eIDAS certificates.
Registering a new certificate will revoke the previous certificate.

Your eIDAS Organization Identifier is one of the mandatory fields that is requested when generating a test certificate. If you do not yet have an eIDAS Organization Identifier, it is sufficient to enter any ETSI TS 119 495 Section 5.2.1 compliant Organization Identifier.

Please keep a copy of the generated Certificate, Private Key and Key Id. You will require this information to sign your API requests.

TPP-Signature-Certificate and SSL-Certificate headers

Where required, you should populate the TPP-Signature-Certificate HTTP header with your signing certificate. In the Sandbox Environment use your test certificate for this purpose. In the Production Environment your eIDAS QSEALC certificate must be used.

In the Sandbox Environment, use your test certificate to also populate the SSL-Certificate HTTP header on all requests. This header is not required in the production environment; instead your eIDAS QWAC must be provided when establishing the Mutual TLS connection.

2. Use your certificate to register your application

The Authorisation process requires that you provide a redirect URI with each authorisation request. This redirect URI must exactly match one of your pre-registered redirect URIs.

The OpenID Connect Dynamic Client Registration Protocol specifies a means of registering your redirect URIs for use in the Authorisation process.

This flow must be successfully completed in order to gain access to the OpenBanking APIs. It is applicable to both the Sandbox and Production Environments.

874874

Get an Initial Access Token

First GET an Initial Access Token from the onboarding endpoint /xs2a-bg/{tenant}/v1/onboarding.

The request must be signed with your signing certificate.

Please note that while the onboarding endpoint is called for a specific tenant, registration is only needed once for your eIDAS organization id.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/onboarding/v1' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: Your signing certificate' 
-H 'Digest: ...' 
-H 'Signature: keyId="...",algorithm="SHA256withRSA",headers="digest",signature="..."'

If successful, the HTTP 200 OK response contains the Initial Access Token and the Link to complete the Registration Process.

{
  "scope": "client-reg",
  "access_token": "...",
  "expires_in": 86400,
  "token_type": "Bearer",
  "_links": {
    "registration": "http://xs2a-sandbox.triodos.com/auth/nl/v1/registration"
  }
}

Use the Initial Access Token to register your redirect URIs

Now POST the Initial Access Token together with your Authorization Code Flow redirect URIs and optionally your Sector Identifier URI.

curl 'http://xs2a-sandbox.triodos.com/auth/nl/v1/registration' 
-H 'Content-Type: application/x-www-form-urlencoded' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: Your signing certificate'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJQU0ROTC1KVVNUSU4tTkNBQVVUSE5VTUJFUiIsImlzcyI6IlRlc3RTZWxmU2lnbmVkQ0EiLCJjbmYiOnsieDV0I1MyNTYiOiI1MzExRDk5RjlGN0Q5MkYxNDM3NTM3NTY5QUZGNUZDRDExNEQwREU0NTFBRkQ5RDI3OEYxQUI3RTQ5QjI5OUQwIn0sImV4cCI6MTU1MDY3NTI0NywiaWF0IjoxNTUwNTg4ODQ3fQ.jTlnoJbk6MkQcnT1NBVE7ld-VD20f25xOOsOyXuCe8w' 
--data 'initial_access_token=...&redirect_uris=...&sector_identifier_uri=...'

HTTP response 201 Created indicates that your registration is successful. The response contains your registered client_id and client_secret. These fields are required by the Authorisation process. The client_secret should be treated as confidential.

{
  ...
  "client_secret": "...",
  "client_id": "...",
  ...
}

📘

Redirect URIs and Client Secret

Your redirect URIs can be updated at any time by replaying this registration flow.

Your client_id will not change as it is bound to your eIDAS organization identifier.

The API Test Client requires the default provided Redirect URIs in order to function correctly.

3. Create a test account in the Sandbox environment

In the Sandbox Environment you can use the API Test Client to create a test account.

Please make a note of the generated IBAN and digipass number. Use the IBAN to initiate payment and account requests. The digipass number is required to authorise the request.

Refer to SCA in the Sandbox Environment for more details.