Team API Authentication and Signature
Access Key, Access Secret, request headers, and HMAC-SHA256 signing rules for Team API.
Team API Authentication and Signature
Team API uses Access Key + Access Secret authentication and signs requests with HMAC-SHA256. This differs from the body-parameter signature used by WaaS / Payment Engine.
Request Rules
Team API communicates over HTTPS and all endpoints use POST requests. Each team has an independent Base URL, and all requests must be sent to that Base URL.
https://{team-domain}/openapi/...Find the Base URL in Cregis App > Management > API Management > API Details. You do not need to pass a Team ID; the system identifies the team from the access domain.
Request Headers
All Team API requests must include these headers:
Access-Key: <access_key>
Access-Timestamp: <unix_millis>
Access-Nonce: <random_nonce>
Access-Signature: <hmac_sha256_signature>| Header | Required | Description |
|---|---|---|
| Access-Key | Yes | API Key identifier used to identify the caller. |
| Access-Timestamp | Yes | Unix timestamp in milliseconds. |
| Access-Nonce | Yes | Random string used to prevent replay attacks. |
| Access-Signature | Yes | Request signature calculated with the Access Secret. |
Authentication Flow
For every request, the server validates the headers, Access Key, timestamp window, nonce, signature, and API permissions. The request continues only after all checks pass.
Timestamp and Nonce
- Access-Timestamp uses a Unix timestamp in milliseconds. The default allowed clock skew is ±300 seconds.
- Access-Nonce should be 16 to 64 characters and must be newly generated for every request.
- The same API Key cannot reuse the same Nonce within the valid time window.
Signature Algorithm and Signing String
All Team APIs use HMAC-SHA256. The signature result is a lowercase hexadecimal string. The signing string is built from these four parts joined with newline characters (\n):
PATH
TIMESTAMP
NONCE
BODY| Field | Source | Description |
|---|---|---|
| PATH | Request path | Excludes protocol, domain, and query parameters, for example /openapi/team/info. |
| TIMESTAMP | Access-Timestamp | Must match the request header. |
| NONCE | Access-Nonce | Must match the request header. |
| BODY | Raw request body | Use an empty string when there is no request body. |
Signature Example
Request: POST /openapi/team/profile, with this body:
{"name":"Demo Team"}Signing string:
/openapi/team/profile
1717380000000
9f7c6a2b47e34f19
{"name":"Demo Team"}Join the four values in order with newlines, run HMAC-SHA256 with the Access Secret, convert the result to lowercase hex, and send it as the Access-Signature header.
Body Signing Rules
- Place all business parameters in the JSON request body. Query String business parameters are not recommended.
- When the request body is empty, use an empty string as BODY for signing.
- When the request body is not empty, sign the raw request body.
- The request body must exactly match the body used during signing, otherwise signature verification fails.
- The body should follow RFC 8785 JSON Canonicalization Scheme (JCS), so object key order, whitespace, number encoding, escaping, and nested structures are consistent across systems.