API 密钥

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

创建密钥

在控制台里打开 API 密钥，选择创建密钥。同一页面上的 API 端点 卡片显示请求要发往的基础 URL，以及一条列出本组织实例的示例命令——它从 $SUPERHEAT_API_KEY 读取密钥。用 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` 密钥由管理员管理，创建时需要管理员会话。创建者被移出组织时，`personal` 密钥随之吊销，`team` 密钥不会。

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

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

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

creator_email 是创建者的邮箱。只用手机号登录、没有邮箱的创建者显示为带国际区号的手机号，例如 +8613800138000。

密钥值只显示一次

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

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

密钥能做什么

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

请求	用 API 密钥
`GET /v1/offers`, `GET /v1/offers/summary`, `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/orders`	`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。personal 密钥只能附加创建它的那个人的 SSH 密钥。team 密钥代表组织行事：它可以附加当前任何一位成员的 SSH 密钥，但不能附加任何已离开的人的——包括它自己的创建者。见添加密钥。

列出密钥

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

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

创建这把密钥的人离开组织后，creator_is_member 就是 false，API 密钥页面会给它标上创建者已离开。personal 密钥这时已经失效，可以吊销它作清理。team 密钥仍然有效——它属于组织——但离开的那个人曾看到过它的密钥值，可能还留着副本，所以页面会提示你吊销它并创建一把新的。

吊销密钥

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

返回 204 No Content。该密钥在下一次发出请求时就失效。在控制台里，密钥旁边的删除图标会先弹出确认框，标题为「吊销“{name}”？」，并说明这是个人密钥还是团队密钥；按吊销密钥才会确认。

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

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

成员被移出组织时

管理员在团队页面移除一名成员时，他在这个组织里创建的 personal 密钥会被立即吊销；个人密钥每次使用时还会重新核对创建者是否仍是成员，所以它们随后都返回 401 TOKEN_INVALID。team 密钥不受影响，创建者离开后照常可用。他用这些密钥部署的实例同样不受影响，会继续运行、继续计费。

所以，CI 这类不该因为某个人离开而中断的自动化，请用团队密钥。团队密钥代表组织行事：通过它的部署可以附加任何一位现任成员的 SSH 密钥，deployed_by 显示的是这把密钥而不是某个人。创建者离开后它不会停止工作，但创建者曾看到过它的密钥值——所以创建它的管理员离开后，请换一把由现任管理员创建的团队密钥，再吊销旧的。参见角色与权限。

创建密钥​

密钥能做什么​

列出密钥​

吊销密钥​

成员被移出组织时​

创建密钥

密钥能做什么

列出密钥

吊销密钥

成员被移出组织时