Skip to main content

Overview

The API has three layers of authentication:

  1. Account authentication is used to identify and authenticate requests from your application. All API requests and UI components require account authentication.

  2. End-user authentication is used to authenticate the Admin User and Authorised Users of the Buyer, i.e. the representatives of the business End Customer. Almost all API requests and UI components require end-user authentication showing that these users are in session and creating the actions/interactions indicated through the API. The end-user authentication is done with an Auth Token which can be used to perform actions within our APIs.

  3. End-user step-up authentication is required when performing certain requests covered by a requirement for Strong Customer Authentication under PSD2 financial regulations. This is achieved by the end user successfully passing an SCA-compliant multifactor challenge, whereupon a stepped-up Auth Token is provided allowing the workflow to proceed.

Depending on the type of operation you are trying to execute, you may be required to either:

  • provide account authentication only or
  • provide account and end-user authentication via an Auth Token
  • provide account and step-up end-user authentication (step-up refers to an Auth Token where two-factor authentication was performed)

Exchanging an Auth Token for an Access Token​

If you support any of the use-cases for Access Token , your programme will need to handle both Auth Tokens and Access Tokens.

info

In our API documentation, we currently refer to auth_token. However, if you are configured for any of the use-cases Root Users linked to multiple identities/Biometrics, this is actually referring to the Access Token.

After completing a successful login, an Auth Token is provided. This token contains information that will identify the user and the method of authentication (password, passcode, biometrics). The Auth Token unlocks very limited functionality.

In order to grant access to the correct identity, the Auth Token needs to be exchanged for an Access Token. The Access Token contains the information that was missing from the Auth Token, namely the identity that the user would like to access.

info

Single login accessing multiple Corporates is a new feature for Embedders who deal with Corporate users. Once activated, it allows an individual end user (root user) to be granted access to multiple Corporates via one primary email+password login, so they can switch back and forth between Corporates without having to log out and log back in with a different email+password. In order to activate this, please contact us.