API 密钥

API 密钥是你交给脚本、CI 任务或自研工具的凭据。它以某一个组织的成员身份做认证，并且不会自行过期。

创建密钥

在控制台里打开 API 密钥，选择创建密钥。用 API 的话：

curl -s -X POST "$SUPERHEAT_API/v1/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "kind": "personal"}'

字段	类型	说明
`name`	字符串，1–64 个字符	必填。密钥在控制台里显示的标签。
`kind`	`personal` 或 `team`	默认为 `personal`。`team` 密钥由管理员管理，创建时需要管理员会话。

响应会返回密钥的元数据和密钥值：

{
  "key": {
    "id": "0f5a1c93-6d21-4e7c-a0b8-3c9f2e1d4a77",
    "name": "ci-pipeline",
    "kind": "personal",
    "prefix": "shk_9f3a21c4",
    "creator_email": "you@example.com",
    "created_at": "2026-07-24T11:02:44.318Z",
    "last_used_at": null
  },
  "secret": "shk_9f3a21c4e0b7d5628a1f3c47b9e0d2a6f81c53d0e7a4b962"
}

密钥值是 shk_ 加 48 个十六进制字符。只有它的前 12 个字符会作为 prefix 存下来，好让控制台告诉你哪个密钥是哪个。

密钥值只显示一次

secret 只在这一次响应里出现，之后再也不会返回。在你关掉对话框或丢弃响应体之前，把它复制到你的密钥库里。丢了就吊销这个密钥，再建一个。

创建密钥需要已登录的会话。密钥不能签发另一个密钥——那会返回 403 ADMIN_REQUIRED。

密钥能做什么

密钥以其创建时所在组织的成员身份行事，与创建它的人是什么角色无关。

请求	用 API 密钥
`GET /v1/offers`, `GET /v1/offers/{id}`, `GET /v1/catalog/status`	允许
`GET /v1/templates`, `GET /v1/templates/{id}`, `GET /v1/templates/by-hash/{hash_id}`, `POST /v1/templates/{id}/duplicate`	允许
`POST /v1/instances`、停止、启动、删除、日志	允许
`GET /v1/billing/transactions`, `GET /v1/billing/spend-daily`	允许
`GET /v1/api-keys`	允许
`GET /v1/me`, `GET /v1/ssh-keys`, `POST /v1/ssh-keys`	`401 TOKEN_INVALID`——账户端点需要会话
`POST /v1/billing/checkout-session`	`403 ADMIN_REQUIRED`——结账仅限管理员
`/v1/orgs/current` 下的邀请与成员管理	`403 ADMIN_REQUIRED`
`POST /v1/api-keys`, `DELETE /v1/api-keys/{id}`	`403 ADMIN_REQUIRED`
任何带着别的组织 `X-Org-Id` 的请求	`403 ORG_MISMATCH`

有两个后果值得提前规划：

密钥不能给余额充值。如果组织的余额用完了，部署就会以 402 INSUFFICIENT_BALANCE 失败，直到管理员在控制台里添加余额。见计费如何运作。
密钥不能添加 SSH 密钥。先在控制台里添加你自己的，部署时再传它的 ssh_key_id。一个密钥能用的 SSH 密钥，就是创建它的那个人账户上的那些。见添加密钥。

列出密钥

curl -s "$SUPERHEAT_API/v1/api-keys" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

返回该组织有效密钥的 {"items": [...]}，最新的在前，每一项都带 id、name、kind、prefix、creator_email、created_at 和 last_used_at。已吊销的密钥不会列出，密钥值也不会再出现。last_used_at 会在该密钥发出的每个请求时更新，这是找出已经没人用的密钥的最快办法。

吊销密钥

curl -s -X DELETE "$SUPERHEAT_API/v1/api-keys/0f5a1c93-6d21-4e7c-a0b8-3c9f2e1d4a77" \
  -H "Authorization: Bearer $SESSION_TOKEN"

返回 204 No Content。该密钥在下一次发出请求时就失效。

谁	能吊销
管理员	组织里的任何密钥
成员	只有自己的 `personal` 密钥
API 密钥	什么都不能——`403 ADMIN_REQUIRED`

吊销一个未知的、已经吊销的，或者属于别的组织的密钥，会返回 404 API_KEY_NOT_FOUND。吊销不会动该密钥部署出来的实例；它们会继续运行、继续计费，直到你把它们停止或销毁。

创建密钥​

密钥能做什么​

列出密钥​

吊销密钥​

创建密钥

密钥能做什么

列出密钥

吊销密钥