Authentication

Token Format

The Agent Token uses a three-part structure, separated by .:

{agent_api_key}.{timestamp}.{signature}

Part	Type	Description	Example
agent_api_key	string	Your API Key	a9f3c28d7b1e4f90c2a1b3d4
timestamp	string	Current Unix timestamp (seconds)	1743055200
signature	string	HMAC-SHA256 signature (lowercase hex)	a1b2c3d4e5...

Signature Algorithm

signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) → lowercase hex

Generation Steps

1. Get current timestamp
   Unix timestamp in seconds, e.g. 1743055200

2. Concatenate the raw string

   raw_string = agent_api_key + "." + timestamp

3. Compute HMAC-SHA256 signature

   signature = HMAC-SHA256(raw_string, agent_api_secret)

   Convert to lowercase hex string

4. Assemble the Token

   token = agent_api_key + "." + timestamp + "." + signature

5. Set HTTP Header

   Authorization: Bearer {token}

Token Expiration

The timestamp in the Token must be within ±2 minutes of the server's current time, otherwise the request will be rejected. Ensure your server clock is accurate (NTP sync recommended).

Server-Side Verification Flow

Steps the server performs upon receiving a request:

1. Extract Token — Get Token from Authorization: Bearer {token} header
2. Split Token — Split by . into agent_api_key, timestamp, signature
3. Verify timestamp — Confirm timestamp is within 2 minutes of server time
4. Lookup secret — Use agent_api_key to retrieve agent_api_secret from database
5. Verify signature — Recompute HMAC-SHA256 with the secret and compare against signature

Mutual Signature Verification

To ensure API security, the authentication mechanism for mutual calls is defined as follows:

1. Agent calls VCT Platform (API Endpoints): The Agent must generate a Token according to the steps above and include it in the Authorization: Bearer {token} request header, which the VCT platform verifies.
2. VCT Platform calls Agent (Callback/Webhook Endpoints): When the VCT platform sends balance, offline reclaim, or other callback requests to the Agent, the request must include an Authorization header. The Agent must verify the Header before verifying the request body's sign. The Header and Body must use exactly the same Unix timestamp:
   • Header format: Authorization: Bearer {agent_api_key}.{timestamp}.{header_signature}
   • Header signature: header_signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret), encoded as lowercase hex
   • agent_api_key must use the Secret belonging to the same Agent; do not try multiple Secrets
   • For single-player callbacks (/balance, /offline, including launch_failed): signature = HMAC-SHA256(username + "." + timestamp, agent_api_secret)
   • For wager data push (/bet-push): signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) The Agent system should process the request only after the sign field matches the calculated signature.