Integration Guide for Banks
[ENG] Integration Guide for Bank
[ENG] Integration Guide for Bank
  • General
    • 💰Overview
      • Transfers between digitized entities
        • Option 1. Fast transfer
        • Option 2. Standard transfer (optional)
      • Version history
      • API change log
      • Glossary
    • 🌐Common requirements
    • 👉Basic use case
    • 📅Integration Plan
      • Integration Plan - Business
      • Integration Plan - Technical Team
      • Multisignature
    • ❗Error messages
  • 🛠️API methods
    • Authentification
      • Authorization via JWT
      • Bank authorization
      • JWT format
    • Emlpoyee
      • How to add a user to a role
      • Role management
    • Customer
      • Segments
    • Digital entity
    • Identifiers
    • Transfer
      • Multisignature for transfers
      • [optional] Callbacks
      • Category
    • Limits
    • Reconciliation
    • [optional] Branch
      • Branch access
      • How to add employee to branch
      • Filter by branch
      • Transfers (branches)
      • Branch digital entity
Powered by GitBook
On this page
  1. API methods
  2. Authentification

Authorization via JWT

JWT is a way for a bank to authorize an operation via call-back

PreviousAuthentificationNextBank authorization

Last updated 1 year ago

JWT is sent at step 3 via a . In case a response fails, the operation is declined.

The system supports 2 ways of JWT creation. Both approaches can be used simultaneously.

⬇️Description
✅Advantage
🤔Drawback

DCM generates a JWT.

Bank validates it against a DCM public key

No efforts to implement:

  • a key storage

  • a function to generate a JWT

Access rules for employees are controlled by DCM.

  • The private key belongs to DCM

  • A csrf_token must be obtained with login-password flow

Header Authorization must contain an actual csrf_token.

⬇️Description
✅Advantage
🤔Drawback

Bank generates a JWT

  • The private key belongs to Bank

  • No need to authenticate with login-password

  1. Efforts to implement

    • a key storage

    • a function to generate a JWT

    • access rules for employees

JWT accompanies all the API requests in header CX-Authorization.

Header Authorization must be empty.

JWT by Bank

At step 2 Bank generates JWT, that is used at step 5 in header CX-Authorization when Bank Employee makes an operation (e.g. creates a new customer). At step 6 DCM validates the JWT. The same does the bank at step 8.

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

Register JWK by bank

To jump-start the flow when JWT by bank is used, please register at least one JWK key in our authentication service for your counterparty.

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

Get list of registered keys for bank JWT

When a JWK is registered, you may check if it exists in our register storage.

Check Bank JWT

This feature allows you to check your JWT in our authentication service with no changes to any objects and processes.

JWT by DCM

Default scheme (when the JWT is created by DCM) allows you to use the role-based access to the features of the processing system.

DCM generates JWT token at step 4. The bank validates it at step 6.

Get list of registered keys for DCM JWT

DCM is capable to manually confirm requests to .

only auto-confirmation is available to

You may verify our JWT in your using our public key by its kid.

🛠️
Bank Auth Service
call-back URL
Process flow for request authorization

Get jwks

get

Get jwks

Path parameters
counterparty_guidstringRequired

Counterparty GUID

Responses
200
OK
application/json
400
json with error msg
application/json
get
GET /api/v1/counterparty/{counterparty_guid}/jwk HTTP/1.1
Host: your_host
Accept: */*
{
  "keys": [
    {
      "created_at": "text",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "guid": "text",
      "updated_at": "text"
    }
  ]
}

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
POST /api/v1/counterparty/{counterparty_guid}/jwk/authenticate HTTP/1.1
Host: your_host
CX-Authorization: text
Accept: */*
{
  "session_token": "text"
}

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
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 by Bank
  • Register JWK by bank
  • POSTCreate jwk
  • Get list of registered keys for bank JWT
  • GETGet jwks
  • Check Bank JWT
  • POSTAuthenticate
  • JWT by DCM
  • Get list of registered keys for DCM JWT
  • GETGet list of registered keys for DCM JWT

Create jwk

post

Create jwk

Path parameters
counterparty_guidstringRequired

Counterparty GUID

Body
Responses
200
OK
application/json
400
json with error msg
application/json
post
POST /api/v1/counterparty/{counterparty_guid}/jwk HTTP/1.1
Host: your_host
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "guid": "text"
}
Identifiers
Identifiers