Authentification

How to log in to the system with an employee credentials

Table of contents

• How to integrate using a JWT?

  • Update a JWK

  • Validate bank's JWT

  • Check list of JWKs by DCM

  • JWT format

• Authorization via callbacks

  • GET /user_auth

  • GET /key

  • GET /external_id

Overview

In order to work with DCM you should be authenticated and authorized in the system.

A JWT token signed by bank's key accompanies every request to API (step 1).

Additional step 3 is used to authorize the request by bank.

How to integrate using a JWT?

Below an example for customer registration is depicted.

• At step 8 the bank is able to validate if the value in X-Session-ID is signed by the DCM key.

• Later at step 7 DCM prepares its own JWT and sends it to Bank API endpoint /user_auth in a header X-Session-ID.

• At step 6 DCM validates the JWT.

• As you can see, at step 2 Bank generates a JWT (in blue) that is sent at step 5 in a header CX-Authorization.

Steps 3-4 are optional and can be used to check if the JWT is valid.

Update a JWK

Initial JWK is uploaded into the system during onboarding (see ). Once your key is about to expire, please register the new JWK key for your counterparty.

Update jwk

put

Update jwk

Path parameters

counterparty_guidstringRequired

Counterparty GUID

jwk_guidstringRequired

JWK GUID

Body

Responses

200

OK

application/json

Responseobject

400

json with error msg

application/json

put

HTTPcURLJavaScriptPython

PUT /api/v1/counterparty/{counterparty_guid}/jwk/{jwk_guid} HTTP/1.1
Host: your_host
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{}

Request body example (JWK)

{"data": {
	"alg": "RS256",
	"e": "AQAB",
	"kid": "54321",
	"kty": "RSA",
	"n": "14FGZls6nrBLY2XH9Dn6UVoY24oynIXJX1PGz6c4wB2Q3DpBj-zPwouhXCQSAGyQB4Co0FN0_pML5g1xSOMY1SccBGZ_CxhdSvyskP01Fr0_rHidIdRIc69k-UPzhnk6Nx_F1uFp8105jUD2Tq_VYIS49rqtct4UQOL5PPzfTOUqBMAEBwvL65KqUAOciC1ae_LV6SHZQXdIqv3EZzA3PxZ4pTa6DvnjgVAbP2zNANUFSnuemvTmQbH05E0qTtGkXugwcc4jCfnOWS4gix2GWDoIhwCi8AbK4aAN-H3D770rF4z4Tb59DEw8-8hZQZtyoJeEi8FWNM1Y6Ki5FMxzpQ",
	"use": "sig"
}}

Validate bank's JWT

The endpoint allows you to check your own JWT in our authentication service.

Authenticate

post

Authenticate

Path parameters

counterparty_guidstringRequired

Counterparty GUID

Header parameters

CX-AuthorizationstringRequired

Counterparty JWT

Responses

200

OK

application/json

400

json with error msg

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/counterparty/{counterparty_guid}/jwk/authenticate HTTP/1.1
Host: your_host
CX-Authorization: text
Accept: */*

{
  "session_token": "text"
}

Check list of JWKs by DCM

The endpoint allows you to get a DCM public key. So, you will be able to check a JWT signed by DCM.

Get list of registered keys for DCM JWT

get

Get list of registered keys for DCM JWT

Responses

200

OK

application/json

400

json with error msg

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/.well-known/jwks.json HTTP/1.1
Host: your_host
Accept: */*

{
  "keys": [
    {
      "alg": "text",
      "e": "text",
      "kid": "text",
      "kty": "text",
      "n": "text",
      "use": "text"
    }
  ]
}

JWT format

JWT is used for all 3 methods in header X-Session-ID to specify "who" (subject) intends to do with "what" (object). The content of JWT must by signed with a bank's private key.

An example of a JWT payload:

An example of a JWT payload:

{
  "flow": "sign-in" // constant: sign-in
  "obj": "123456789", // object - identifer of a customer (e.g. IBAN or phone number)
  "sub": "[e-mail]", // subject identifier
  "iat": 1684501806, // issued at
  "exp": 1684501806, // expires at
}

So, when a callback is received on bank's side, it is possible for your systems to check a signature, object and subject that you placed into an initial request to API methods of TPN.

Example of a full signed JWT:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjljMzdlYjc5LWI2YmYtNDQzNC1hYzNhLTM1NTZjOGI0YjBmNyIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTIxNzIzODUsImZsb3ciOiJzaWduLXVwIiwiaWF0IjoxNjkyMTcyMDg1LCJvYmoiOiJlbWlzc2lvbl8wIiwic3ViIjoiYWRtaW5fYmFuazFAc3RhZ2UudGVzdCJ9.Woh-N-4jeK90rmSbOtAZLno4rCBnWBUOi-PaB6as1lnips966Io19tiK5RQ0aDOoFTrRkGbm01HlDZpHxquI2-BMJfqifY7_QYknge1mHiGIn1lw6W4fBaYcHT2MPJ59ATvzAlt-WMxI6jppsH0tK4ITIUXOfsf6F6flFr1gfWu2HAmys1jxWnKuzRcFpm24Vjoij5exoBlb3wJUaIzJCezJmEAeAqtENZyzpozwRzthDbxhFvkDrm78mMfmjvvvwqdsSAjmKj7apnx0qOqRuKhiFZNbs9aftQqWIGPZ3VaTWIXgksLxiY5xVcf275awYmtZBD7mHeRNIwVYUDWzMQ

The content can be decoded here.

If all the checks pass on your side, a successful response (see details below) should be sent. Otherwise an HTTP 401 (Unauthorized) is expected.

Authorization via callbacks

3 API methods on Bank's side are required to share the account ownership between Bank and DCM.

Method	Path	Purpose
GET	/user_auth	user data
GET	/key	user secret key
GET	/external_id	authentication

It is expected for each method to respond within 1 second.

Callback specification

GET /user_auth

Request example:

curl "https://{bank's auth host}/user_auth" --header "X-Session-ID:token"

Response example:

{
"external_id":"123456789", // up to 500 symbols
"first_name":"mock",
"last_name":"mock",
"email":"[e-mail]",
"phone":"[phone]",
"key":"secret"
}

Attributes external_id, key and phone are obligatory in response.

GET /key

Request example:

curl "https://{bank's auth host}/key" --header "X-Session-ID:token"

Response example:

{
"key":"secret"
}

GET /external_id

Request example:

curl "https://{bank's auth host}/external_id" --header "X-Session-ID:token"

Response example:

{
"external_id":"123456789"
}