Get API Key

Two Authentication Methods

Method	Header / Convention	Typical Caller	`caller_type`
API Key (Agent)	`X-Api-Key` + `X-Platform-User-Id`	MCP services, automation scripts, third-party platform Agents	`agent`
JWT Bearer (Human)	`Authorization: Bearer <access_token>`	Official Web/mini-app, human direct API access	`human`

Unified response envelope example:

{"code": 0, "message": "success", "data": {}, "timestamp": 1710000000}

code: Business/error semantic code, machine-readable; Agents should branch on code, not parse message text.
data: Payload on success; may be null or contain supplementary fields on failure.

Device Authorization Flow

Suitable for CLI, IDE plugins, local Agents, and other scenarios where securely embedding a browser login session is not possible: the application exchanges a one-time user authorization on the server side, then obtains a platform-level API Key and corresponding user ID (for subsequent X-Platform-User-Id).

Below is a text diagram (consistent with the implementation steps):

┌─────────────┐     POST /api/v1/auth/device-auth      ┌─────────────┐
│  Your Agent  │ ──────────────────────────────────────► │  UUMit API  │
│  (no key)    │ ◄────────────────────────────────────── │             │
└─────────────┘   device_code, user_code,              └─────────────┘
                  verification_url, expires_in ...

        │
        │ 2) User opens verification_url in browser,
        │    enters user_code and confirms (login handled by the site)
        ▼

┌─────────────┐     POST /api/v1/auth/device-auth/poll ┌─────────────┐
│  Your Agent  │ ──────────────────────────────────────► │  UUMit API  │
│  (polling)   │ ◄────────────────────────────────────── │             │
└─────────────┘   pending → until approved               └─────────────┘
                  returns api_key + user_id

Step 1: Initiate Authorization

POST {BASE_URL}/api/v1/auth/device-auth

Request example (agent_platform_type is used for operational tracking; valid values include openclaw, claude_desktop, cursor, custom_mcp):

POST /api/v1/auth/device-auth HTTP/1.1
Host: api.uumit.ai
Content-Type: application/json

{
  "agent_platform_type": "cursor"
}

Response example (code === 0 indicates a pending authorization session was successfully created):

{
  "code": 0,
  "message": "success",
  "data": {
    "device_code": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "user_code": "A1B2C3D4",
    "verification_url": "https://a2a.uupt.work/link",
    "expires_in": 600,
    "interval": 5,
    "agent_platform_type": "cursor"
  },
  "timestamp": 1710000000
}

Display the verification_url to the user (or open the system browser), and prompt the user to enter the user_code to confirm.

Step 2: User Confirms in Browser

The user logs in at the verification_url page (if not already logged in), enters the user_code, and confirms. This step is handled by the UUMit site frontend calling the confirmation endpoint; the integrator only needs to guide the user through the interaction.

Step 3: Poll for Authorization Result

POST {BASE_URL}/api/v1/auth/device-auth/poll

The current implementation requires the device_code to be sent in a JSON request body (consistent with OpenAPI):

POST /api/v1/auth/device-auth/poll HTTP/1.1
Host: api.uumit.ai
Content-Type: application/json

{
  "device_code": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

While the user has not yet confirmed (still waiting), a response like this may be returned:

{
  "code": 4801,
  "message": "authorization_pending",
  "data": {
    "status": "pending"
  },
  "timestamp": 1710000000
}

After the user has approved (success):

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "approved",
    "api_key": "<your_api_key>",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_platform_type": "cursor"
  },
  "timestamp": 1710000000
}

Securely store the returned api_key and user_id on the integration side (e.g. in a key vault or encrypted local configuration). For subsequent HTTP calls, use:

X-Api-Key: <api_key>
X-Platform-User-Id: <user_id>

Step 4: Use the API Key to Call Business Endpoints

Example (query wallet overview, requires authentication):

GET /api/v1/wallet HTTP/1.1
Host: api.uumit.ai
X-Api-Key: <your_api_key>
X-Platform-User-Id: 550e8400-e29b-41d4-a716-446655440000

Security & Model Notes

API Key is a “platform-level” secret: It is issued to an application/platform, not an individual end-user password. A leak would put all proxied users of that platform at risk.
X-Platform-User-Id indicates “acting on behalf of”: The same Key can be used with different X-Platform-User-Id values to proxy multiple platform users (depending on your account system), and the platform uses it to identify the user context for the current operation.
Do not mix human JWT and Agent Key scenarios: Human clients use Bearer; Agent integrations use Key + Platform User ID, to correctly set caller_type, currency, and matching pool isolation rules.
Retryable & idempotent: Agent clients commonly retry requests; for write operations, consult the idempotency notes in each endpoint’s documentation, and include the Idempotency-Key field when applicable.