Authentication Guide - DCS Technical Documentation

Whether you are an exchange, a wallet or a platform, once DCS has issued you a key pair you can call every DeCard-Managed API with a single, uniform signing rule. This page gets authentication working in one pass. As a licensed issuer with its own BINs, DCS requires a verifiable request origin and replay protection on every API call.

Naming note: this documentation set covers the DeCard-Managed integration model, previously called the standard-authorization model. In this model DCS maintains a dedicated fiat / digital-asset account and balance for each user, and no on-chain collateral is involved.

What is in this group

Integration Resources brings together every technical asset and security credential you need, from integration development through to production go-live:

Sub-page	Purpose
Authentication Guide (this page)	API Key / Secret Key management and HMAC-SHA256 request signing
IP Whitelisting	Register your network egress addresses with DCS, both for API access and for secure retrieval of production credentials
SessionId Public Key / Encryption	The encryption and signing capabilities actually available in the DeCard-Managed model
H5 KYC / Card Application Journey	The embedded H5 flow for KYC and card application
Web SDK Integration	Front-end integration SDK
Webhook + WebSocket Notifications	Event callbacks (Webhook) and real-time WebSocket push (a DeCard-Managed differentiator)

1. Credentials and Request Headers

What DCS gives you

Field	Description	Provided by
`apiKey`	Globally unique identifier for API calls, used for identification and request-origin tracing	DCS
`secretKey`	The key used to compute the request signature. Keep it safe and never disclose it to any third party	DCS

The apiKey is a globally unique identifier that supports identification and analytics. To stop anyone else from issuing requests under your apiKey, it must be paired with the secretKey: you generate a signature according to the agreed rules and submit it alongside the request for DCS to verify. DCS delivers this key pair to you privately, and every API call a partner makes must follow the agreed signing protocol.

For sandbox apiKey/secretKey, contact the DCS team. Production credentials must be obtained through Secure Retrieval of Production Credentials.

Headers required on every request

Every API call from a partner must carry the following HTTP headers:

Header	Required	Description
`Content-Type`	REQUIRED	Fixed to `application/json` when the request body is JSON. If absent, DCS returns HTTP 400 with business code `SYS_ILLEGAL_PARAM`
`X-DAPI-API-KEY`	REQUIRED	The `apiKey` issued by DCS
`X-DAPI-TIMESTAMP`	REQUIRED	Request timestamp in milliseconds, used for replay protection
`X-DAPI-NONCE`	REQUIRED	Random number in the range `[10000, 99999]`, making each request single-use
`X-DAPI-SIGN`	REQUIRED	The HMAC-SHA256 signature computed as described below (lowercase hexadecimal)

the secretKey is used only to compute the signature locally. Never transmit it in a request header.

Typical response when Content-Type: application/json is missing:

{"code":"SYS_ILLEGAL_PARAM","message":"illegal param","messageDetail":null,"data":null,"success":false}

This success=false comes from the framework-level error response triggered by the missing Content-Type; it does not mean that every business response reliably includes success. In normal integration, always decide success or failure from code and do not depend on the success field.

2. Request Signing (HMAC-SHA256)

Signing rule

Sign the concatenated string using the HmacSHA256 algorithm with the secretKey as the key:

X-DAPI-SIGN = HmacSHA256( apiKey + timestamp + nonce + payload , secretKey )

The output is a lowercase hexadecimal string. The segments of the concatenated string:

Segment	Value
`apiKey`	Same as `X-DAPI-API-KEY`
`timestamp`	Same as `X-DAPI-TIMESTAMP` (millisecond timestamp)
`nonce`	Same as `X-DAPI-NONCE`
`payload`	GET requests: the URL-encoded query string; all other methods: the raw request body

if method is GET:
    payload = url.encodedQuery()     // e.g. externalUserId=<externalUserId>&cardMantissa=1670
else:
    payload = body                   // the raw JSON request body string

The signing algorithm is fixed to HmacSHA256. Always use this algorithm.

Replay protection (DCS verifies, the partner generates)

TIMESTAMP: must be a 13-digit millisecond timestamp (for example Date.now(), not a 10-digit second timestamp). A malformed value returns DAPI_TIMESTAMP_FORMAT_ERROR. DCS only accepts requests within a 5-second validity window; beyond that it returns DAPI_TIMESTAMP_EXPIRED, so regenerate the timestamp from the current time, recompute the signature, and keep your local clock in sync.
NONCE: generate a fresh random number in [10000, 99999] for every request so that each request is valid only once. Do not reuse nonces.

If authentication fails, check the timestamp, the nonce and the string you signed first. For exact error codes, rely on what the API actually returns and on the dictionary DCS provides for this product.

Signing examples

JavaScript (Postman pre-request script)

const CryptoJS = require('crypto-js');

const apiSecret = '<your-secret-key>';
const apiKey    = '<your-api-key>';

// GET uses the query string; other methods use the request body. Concatenate whichever applies
const queryParams  = '<your-query-param>';   // e.g. externalUserId=<externalUserId>&cardMantissa=1670
const requestBody  = '<your-request-body>';  // the raw body for POST/PUT
const nonce        = 10010;
const timestamp    = Date.now().toString();

const dataToSign = apiKey + timestamp + nonce + queryParams + requestBody;
const signature  = CryptoJS.HmacSHA256(dataToSign, apiSecret).toString(CryptoJS.enc.Hex);

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;

public final class HmacSignature {
    private static final String HMAC_SHA256 = "HmacSHA256";

    public static String getSignature(String apiSecret, String data) throws Exception {
        SecretKeySpec keySpec = new SecretKeySpec(apiSecret.getBytes(), HMAC_SHA256);
        Mac mac = Mac.getInstance(HMAC_SHA256);
        mac.init(keySpec);
        byte[] hmac = mac.doFinal(data.getBytes());
        return Hex.encodeHexString(hmac);
    }
}

Full request example (GET)

curl --location 'https://{domain}/card/v2/detail?externalUserId=<externalUserId>&cardId=<cardId>' \
  --header 'Content-Type: application/json' \
  --header 'X-DAPI-API-KEY: <your-api-key>' \
  --header 'X-DAPI-SIGN: <calculated-signature>' \
  --header 'X-DAPI-TIMESTAMP: <millis-timestamp>' \
  --header 'X-DAPI-NONCE: <random-10000-99999>'

In this example payload = externalUserId=<externalUserId>&cardId=<cardId>, the GET query string. To validate your implementation before go-live, take the same apiKey/timestamp/nonce/payload set that DCS provides and confirm you reproduce the identical X-DAPI-SIGN.

Every externalUserId, apiKey, X-DAPI-SIGN, TIMESTAMP and NONCE in the examples is a placeholder and must not be treated as a real value. The DeCard-Managed model handles a large volume of end-user personal data, so debug logs must not record real credentials or PII either.

Common response envelope

Every API returns the same envelope:

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": {
    "message": "",
    "title": "",
    "type": "",
    "icon": "",
    "action": "",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": ""
}

Field	Type	Description
`code`	string	Business status code. `SYS_SUCCESS` on success, a specific error code on failure
`message`	string	Short message, normally empty on success
`messageDetail`	object	Structured display object containing `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`, usable for front-end prompts. Its fields are normally empty on success. Do not use it to decide success or failure; always judge the outcome from `code`
`data`	object	The business payload

Treat code == "SYS_SUCCESS" as the sole success condition. The response envelope does not include a success boolean, so do not depend on that field.

3. Secure Retrieval of Production Credentials

To keep production apiKey/secretKey from leaking in transit, production credentials are never sent to you directly. They are collected through a one-time secure retrieval flow.

The sandbox environment does not need this flow; simply contact the DCS team.

The flow (and who does what)

The partner provides: one secure email address plus one source IP for retrieval.
- The email address receives the retrieval instructions; the IP is added to the credential-retrieval whitelist.
DCS sends: an email to that secure address containing a temporary secure link that is valid for one use only.
The partner retrieves: concatenate extractUrl with extractSecretKey and run it from the machine at the registered IP to receive the apiKey/secretKey.

Fields in the email

Field	Type	Description
`expireTime`	string	Validity period of the retrieval security code
`extractSecretKey`	string	Credential-retrieval security code
`extractUrl`	string	Credential-retrieval URL
`howToUse`	string	Usage instructions
`notes`	string	Reminder that the link can be used for one retrieval only

Success response

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "expireTime": "2024-10-21T16:52+08:00[Asia/Shanghai]",
    "extractSecretKey": "<one-time-extract-secret>",
    "extractUrl": "https://{domain}/internal/open-api/v1/secret-extract/",
    "howToUse": "Please concatenate the url with the secret-key and execute it on the specified machine.",
    "notes": "This link is only valid for one AKSK extraction, if the content is not properly accessed, the AKSK may have been compromised, please contact us promptly."
  }
}

Failure response

{
  "code": "ERROR-CODE",
  "message": "simple describe, see error-code list",
  "messageDetail": null,
  "data": null
}

Only the failure envelope is shown here. For exact error codes, rely on what the API actually returns and on the dictionary DCS provides for this product; this version does not reuse error-code tables from other products.

If retrieval fails: the link may already have been used inside its validity window, which means the credentials could be compromised. Contact your DCS business contact immediately and repeat the email flow to have them reissued.The retrieval IP does not have to be the same as your day-to-day API calling IP; declare each purpose to DCS separately. For how to submit them, see IP Whitelisting.

With authentication working, go to Quickstart to issue your first card, or start from First Steps to confirm that your account and callbacks are ready. The remaining technical assets in Integration Resources:

IP Whitelisting: register your network egress addresses with DCS, both for API access and for secure retrieval of production credentials.
SessionId Public Key / Encryption: the encryption and signing capabilities actually available in the DeCard-Managed model.
H5 KYC / Card Application Journey: the embedded flow for KYC and card application.
Web SDK Integration: front-end integration SDK.
Webhook + WebSocket Notifications: event callbacks (Webhook) and real-time WebSocket push (a DeCard-Managed differentiator).

​What is in this group

​1. Credentials and Request Headers

​What DCS gives you

​Headers required on every request

​2. Request Signing (HMAC-SHA256)

​Signing rule

​Replay protection (DCS verifies, the partner generates)

​Signing examples

​Full request example (GET)

​Common response envelope

​3. Secure Retrieval of Production Credentials

​The flow (and who does what)

​Fields in the email

​Next steps / Related

What is in this group

1. Credentials and Request Headers

What DCS gives you

Headers required on every request

2. Request Signing (HMAC-SHA256)

Signing rule

Replay protection (DCS verifies, the partner generates)

Signing examples

Full request example (GET)

Common response envelope

3. Secure Retrieval of Production Credentials

The flow (and who does what)

Fields in the email

Next steps / Related