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