Authentification

How to log in to the system with an employee credentials

Table of contents

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
put
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
post
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
get
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": "[email protected]", // 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":"[email protected]",
"phone":"+12345678901",
"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"
}

PreviousError messagesNextCustomer

Last updated