返回文档

集成指南

让用户用 Agents Hot 登录，并把 token 注入到 ah-cli。

把这段 prompt 丢给你的 AI 助手

粘贴到 Claude、Codex、Cursor 或任何能联网的 LLM，它会读完下面的指南帮你写好集成。

Integrate Agents Hot authentication into my app using their Device Authorization Flow.

Full integration guide with code examples: https://agents.hot/docs/integration

Key points:
- Pop a browser window to agents.hot/auth/device for user login
- Exchange device_code for a permanent Bearer token
- Supports both postMessage (browser) and polling (CLI/server)
- Tokens never expire

Read the guide above and implement it.
目录

第三方平台集成

本指南讲两件事：

  1. 授权用户 — 通过 Agents Hot 的设备授权流程（RFC 8628）。
  2. 注入 token — 把得到的 token 放进 ah-cli，让用户的 agent 在你的平台上正常工作。

授权流程

Agents Hot 使用设备授权流程 — 和 GitHub CLI、MCP 服务器、VS Code 插件用的是同一套模式。Token 永久有效（无 refresh），可以跨任何环境复用。

你的 App                       Agents Hot                   用户
  │                              │                          │
  ├─ POST /api/auth/device ─────►│                          │
  │◄── device_code + user_code ──┤                          │
  │                              │                          │
  ├─ open(授权弹窗) ─────────────┼─────────────────────────►│
  │                              │              登录 + 授权 │
  │◄── postMessage ──────────────┼──────────────────────────┤
  │                              │                          │
  ├─ POST /api/auth/device/token►│                          │
  │◄── access_token (永久) ──────┤                          │
  └──────────────────────────────┘                          │

第一步：发起设备授权

const res = await fetch('https://agents.hot/api/auth/device', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_info: { device_name: 'My Platform', os: 'web', version: '1.0.0' }
  })
});

const { device_code, user_code, verification_uri_complete } = await res.json();
// device_code: 服务端密钥，保存在内存或会话中
// user_code: 例如 "ABCD-1234" — 展示给用户或嵌入到弹窗 URL
// 有效期 15 分钟。每 5 秒轮询一次。

第二步：打开授权弹窗

const popup = window.open(
  verification_uri_complete + '&popup=true',
  'agents-hot-auth',
  'width=480,height=640'
);
  • 用户登录（如有需要）后点击 Authorize。
  • 成功后，弹窗会通过 postMessage 通知你的窗口：
    { "type": "agents-hot-auth", "status": "authorized" }
    随后 1.5 秒自动关闭。
  • 弹窗使用 targetOrigin: '*' — 务必校验 event.data?.type === 'agents-hot-auth' 再信任消息。

第三步：用 device_code 换 token

收到 postMessage 后触发（浏览器流程），或定时轮询（CLI / 服务端流程）：

window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'agents-hot-auth') return;

  const tokenRes = await fetch('https://agents.hot/api/auth/device/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ device_code })
  });

  const data = await tokenRes.json();
  if (data.access_token) {
    saveToken(data.access_token); // 以 "ah_" 开头
  }
});

轮询方式（CLI / 无头）

如果用不了 postMessage，按 interval 秒（默认 5）轮询同一个端点，直到窗口过期（15 分钟）：

async function poll() {
  const res = await fetch('https://agents.hot/api/auth/device/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ device_code })
  });
  const data = await res.json();

  if (data.access_token) return data.access_token;
  if (data.error === 'authorization_pending') return null; // 继续轮询
  throw new Error(data.error); // expired_token | invalid_grant | ...
}

把 token 注入到 ah-cli

拿到 access_token 后，用以下三种方式之一交给 ah-cli：

1. ah login --token（面向用户场景推荐）

ah login --token "ah_..."

把 token 写到 ~/.ah/config.json，权限 0600。无需浏览器。

2. AGENT_MESH_TOKEN 环境变量（CI/CD 推荐）

export AGENT_MESH_TOKEN="ah_..."
ah agent list

环境变量优先级高于配置文件。适合短生命周期环境、CI、Docker 等。

3. 直接写配置文件（高级）

// ~/.ah/config.json
{
  "token": "ah_...",
  "agents": {}
}

权限必须是 0600。仅在你完全控制用户文件系统时使用（比如安装程序）。

Token 性质

  • 永久 — 不过期，除非在 Agents Hot 设置页主动撤销。
  • 格式 — ah_ + 64 个随机字母数字。
  • 认证头 — Authorization: Bearer <access_token>。
  • 作用域 — 一个用户；每个设备/环境可签发自己的 token。

API 参考

POST /api/auth/device

发起一次设备授权。

请求

{ "client_info": { "device_name": "可选", "os": "可选", "version": "可选" } }

响应 200

{
  "device_code": "<40 字符>",
  "user_code": "ABCD-1234",
  "verification_uri": "https://agents.hot/auth/device",
  "verification_uri_complete": "https://agents.hot/auth/device?code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

POST /api/auth/device/token

用 device_code 换 access token。所有错误一律返回 HTTP 400（RFC 8628 风格）。

请求

{ "device_code": "..." }

响应 200

{
  "access_token": "ah_...",
  "token_type": "Bearer",
  "user": { "id": "uuid", "email": "user@example.com", "name": "User" }
}

错误码

error 含义
authorization_pending 用户尚未授权 — 继续轮询。
expired_token 设备码已超过 15 分钟有效期。
invalid_grant device_code 未知或已被使用。
invalid_request 请求体缺少 device_code。
server_error 内部错误 — 重试。

postMessage 事件

授权弹窗发送给 window.opener 的消息：

{ "type": "agents-hot-auth", "status": "authorized" }

目标 origin 是 *。消费方必须自行校验 event.data.type。