API 令牌

API 令牌也叫 API 密钥，它让脚本、CI 作业、CLI、SDK、Terraform 或 AI 智能体以你的身份在 Cloady 上操作。它发出的每个请求都以你的账号运行，只能访问你所属的工作区，使用你在每个工作区中的角色，并受令牌权限范围的限制。

令牌的格式是 cldy_ 后跟 48 个十六进制字符：

cldy_3f9a1c07d2b84e65a0c9e1f4b7d2a8c6e05f19b3a7d4c2e8

在控制台中创建令牌

1. 点击右上角的账号头像，然后点击 Account settings。
2. 打开 API tokens 标签页，点击 + New token。
3. 为令牌填写一个能说明用途的名称，例如 GitHub Actions 或 CLI · laptop。之后你会在列表中看到这个名称。
4. 选择权限范围：Read only、Deploy only 或 Full access。各自允许的操作，请参阅权限范围。
5. 选择有效期：No expiry、30 days、90 days 或 1 year。
6. 点击 Create token。
7. 立即复制令牌。 Cloady 只显示一次，并且只保存它的哈希值，所以无法再次显示。如果丢失了，请吊销它并新建一个。

请把令牌保存在安全的地方，例如 CI 服务的密钥存储或密码管理器。切勿把它粘贴到支持工单、聊天或公开仓库中。

权限范围

每个令牌有一个权限范围。权限范围设定了令牌能使用的最高工作区角色；在此之上，你自己在每个工作区中的角色依然适用。

请选择能完成任务的最小权限范围：

• 负责部署的 CI 流水线或 AI 编程智能体：Deploy only。
• 只读取数据的仪表板、监控或报表：Read only。
• 创建工作区的 Terraform，或任何会更改计费的操作：Full access。

超出令牌权限范围的请求会得到 403 forbidden，即使你在该工作区中的角色更高。

使用令牌

HTTP API

在发往 https://cloady.com/api 的每个请求中，以 Bearer 令牌的形式发送令牌：

curl https://cloady.com/api/workspaces \
  -H "Authorization: Bearer cldy_…"

CLI

cloady login cldy_…

CLI 会把令牌保存在 ~/.config/cloady/config.json 中。它也会读取环境变量 CLOADY_TOKEN，很适合 CI 作业；任何命令也都接受 --token cldy_…。参见 CLI 指南。

SDK

import { createCloady } from "@cloady/sdk";

const cloady = createCloady({ auth: process.env.CLOADY_TOKEN });

from cloady import Cloady

cloady = Cloady(base_url="https://cloady.com", token="cldy_…")

Terraform

Provider 会读取 CLOADY_TOKEN，或 provider 块中的 token 参数。参见 Terraform 指南。

export CLOADY_TOKEN=cldy_…

MCP

@cloady/mcp 服务器从 BEARER_TOKEN_CLOADY 读取令牌：

claude mcp add cloady -e BEARER_TOKEN_CLOADY=cldy_… -- npx -y @cloady/mcp

连接托管服务器 https://cloady.com/api/mcp 的客户端则改为通过你的浏览器登录，由 Cloady 为它们创建令牌。参见 MCP 指南。

Cloady 为你创建的令牌

有些登录方式会代表你创建令牌，这些令牌也显示在同一个列表中：

• 不带令牌运行 cloady login 时，它会通过浏览器让你登录，并创建一个名为 Cloady CLI 的令牌。
• 把 MCP 客户端或 Claude、ChatGPT 等 AI 应用连接到 Cloady 时，会创建一个以该客户端命名的令牌，其权限范围就是你在授权同意页面上选择的那个。

吊销其中某个令牌，会让对应的工具退出登录。

通过 API 创建令牌

具有 Full access 的令牌或已登录的浏览器会话，可以创建另一个令牌：

curl https://cloady.com/api/me/tokens \
  -H "Authorization: Bearer cldy_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "GitHub Actions", "scope": "deploy", "expires": "90d"}'

响应包含新令牌的详细信息，以及仅返回这一次的令牌值，位于 secret 中：

{
  "token": {
    "id": "…",
    "name": "GitHub Actions",
    "scope": "deploy",
    "prefix": "cldy_3f9a1c0",
    "workspaceId": null,
    "lastUsedAt": null,
    "expiresAt": "2027-02-01T12:00:00.000Z",
    "createdAt": "2026-11-03T12:00:00.000Z"
  },
  "secret": "cldy_…"
}

完整参考请参见 createToken、listTokens 和 revokeToken。

查看和吊销令牌

Account settings → API tokens 列出所有有效的令牌，包括名称、权限范围、令牌值的前 12 个字符（cldy_3f9a1c0）、最近使用时间和过期时间。点击 Revoke 即可停用令牌，它会立即失效。

通过 API，GET /api/me/tokens 列出你的令牌，DELETE /api/me/tokens/{id} 吊销其中一个。

当使用令牌的人员、机器或服务不再需要它时，请吊销它；如果令牌可能已泄露，请立即吊销。然后新建一个。

错误

关于权限范围与工作区角色在每个请求中如何共同生效，请参阅 API 概览。