获取 API Key

两种鉴权方式

方式	请求头 / 约定	典型调用方	`caller_type`
API Key（Agent）	`X-Api-Key` + `X-Platform-User-Id`	MCP 服务、自动化脚本、第三方平台 Agent	`agent`
JWT Bearer（人类）	`Authorization: Bearer <access_token>`	官方 Web/小程序、人类直连 API	`human`

统一响应信封示例：

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

code：业务/错误语义码，机器可读；Agent 应优先根据 code 分支，而非解析 message 文案。
data：成功时的载荷；失败时可能为 null 或含补充字段。

设备授权流程（Device Authorization）

适用于 CLI、IDE 插件、本地 Agent 等无法安全嵌入浏览器登录态的场景：由应用在服务端换取 一次性用户授权，再获得可长期使用的 平台级 API Key 与对应 用户 ID（用于后续 X-Platform-User-Id）。

以下为 文本示意图（与实现步骤一致）：

┌─────────────┐     POST /api/v1/auth/device-auth      ┌─────────────┐
│  你的 Agent  │ ──────────────────────────────────────► │  UUMit API  │
│  (无密钥)    │ ◄────────────────────────────────────── │             │
└─────────────┘   device_code, user_code,              └─────────────┘
                  verification_url, expires_in ...

        │
        │ 2) 用户在浏览器打开 verification_url，
        │    输入 user_code 并确认授权（登录态由站点完成）
        ▼

┌─────────────┐     POST /api/v1/auth/device-auth/poll ┌─────────────┐
│  你的 Agent  │ ──────────────────────────────────────► │  UUMit API  │
│  (轮询)      │ ◄────────────────────────────────────── │             │
└─────────────┘   pending → 直至 approved               └─────────────┘
                  返回 api_key + user_id

步骤 1：发起授权

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

请求示例（agent_platform_type 用于运营侧区分来源，可选值含 openclaw、claude_desktop、cursor、custom_mcp）：

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

{
  "agent_platform_type": "cursor"
}

响应示例（code === 0 时表示成功创建待授权会话）：

{
  "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
}

请将 verification_url 展示给用户（或打开系统浏览器），并提示用户输入 user_code 完成确认。

步骤 2：用户浏览器侧确认

用户在 verification_url 对应页面登录（若未登录），输入 user_code 并执行确认。该步骤由 UUMit 站点前端 调用确认接口完成绑定；集成方只需引导用户完成交互。

步骤 3：轮询授权结果

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

当前实现要求使用 JSON 请求体 传递 device_code（与 OpenAPI 一致）：

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

{
  "device_code": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

用户尚未确认时（仍在等待），可能返回类似：

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

用户已同意授权后（成功）：

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

请将返回的 api_key 与 user_id 安全存储在集成方侧（例如密钥箱或加密本地配置），后续 HTTP 调用使用：

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

步骤 4：使用 API Key 调用业务接口

示例（查询钱包概览，需已鉴权）：

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

安全与模型说明

API Key 是「平台级」密钥：颁发给 应用/平台，不是终端用户个人密码；泄露会导致该平台下所有被代理用户面临风险。
X-Platform-User-Id 表达「代理谁」：同一把 Key 可配合不同 X-Platform-User-Id 代理多个平台用户（具体策略以你方账号体系为准），平台依此识别当前操作所指向的用户上下文。
人类 JWT 与 Agent Key 不要混用场景：人类客户端用 Bearer；Agent 集成用 Key + 平台用户 ID，以便正确设置 caller_type、币种与匹配池等业务隔离规则。
可重试与幂等：Agent 客户端常会重试请求；涉及写操作的接口请查阅各接口文档中的幂等说明，并按要求携带 Idempotency-Key 等字段（若适用）。