API Guide
Authentication & Authorization
Tenant headers, JWT-based authentication, request encryption, and role-based access control (RBAC) for DCMS APIs.
Tenant Header
Every API request must include the TENANT header — a unique identifier assigned during onboarding.
TENANT: BANK_TENANT_IDThe tenant header determines:
- Which bank's data the request operates on
- Which product configuration applies
- Which CBS connector to use
- Which notification channels are active
Required on Every Request
Requests without a valid TENANT header will return 400 Bad Request with error code tenant.header.missing.
JWT Authentication
DCMS uses JWT (JSON Web Token) based authentication.
Obtain Token
POST /api/authenticate
Content-Type: application/json{
"username": "api_user",
"password": "encrypted_password"
}{
"id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Use Token in Requests
Include the token in the Authorization header along with the TENANT header:
POST /card/activate
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
TENANT: BANK_TENANT_ID
Content-Type: application/json| Property | Detail |
|---|---|
| Type | JWT (JSON Web Token) |
| Expiry | Configurable — typically 1 hour |
| Refresh | Re-authenticate to obtain a new token |
| Scope | Token scoped to the authenticated user's role and permissions |
Request Encryption
For sensitive operations (PIN, card data), the gateway supports encrypted request bodies:
| Property | Detail |
|---|---|
| Algorithm | ECDH key exchange + AES-256 |
| Key Exchange | Encryption keys exchanged during onboarding |
| Decryption | Handled automatically at the gateway |
| Sensitive Responses | Fields like card number and CVV encrypted in response |
Security Requirement
PIN values must never be sent in clear text. Always use the encrypted PIN block format (HSM-compatible) provided during onboarding.
Role-Based Access Control (RBAC)
| Role | Access Level |
|---|---|
| Admin | Full access — all APIs including configuration and user management |
| Operations | Card lifecycle, customer management, reporting |
| Read-Only | View-only — card details, transaction history, reports |
| API Integration | Programmatic access for system-to-system integration |