Connect Token

Purpose

This is the primary token issuance flow for client integrations.

It is a single-step call on the mobile API.

Base URL

Use the mobile API base:

• Mobile API base: <MOBILE_API_BASE_URL>/api/v1
• Full route: <MOBILE_API_BASE_URL>/api/v1/connect/token

Endpoint

POST /api/v1/connect/token

Required Headers

Request Body

{
  "device_id": "mobile-device-001",
  "timestamp": "1740892800",
  "user_id": "agent-user-10001"
}

Signature Rule

Build the signing message using this exact order:

agent_uuid + device_id + timestamp + user_id

Then generate:

signature = hex(HMAC_SHA256(message, agent_secret))

timestamp must be within roughly +/- 5 minutes of server time.

Success Response

{
  "trace_id": "",
  "status_code": 200,
  "message": "Login successful",
  "data": {
    "access_token": "2ca6b427-07d2-4026-9566-55e5d80b3af0",
    "expired_at": 1741092800
  }
}

Important Behavior

• This endpoint returns access_token and expired_at only (no refresh_token).
• Access-token lifetime is currently about 30 minutes from issuance.
• When token expires, call /api/v1/connect/token again to issue a new access token.

Common Failures

• Missing X-Agent-ID or X-Signature
• Invalid agent ID or agent secret
• Invalid HMAC signature
• Invalid or expired timestamp window
• Missing device_id, timestamp, or user_id