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。

金鑰能做什麼

金鑰以其建立時所屬組織的 member 身分運作，不論建立者本人的角色為何。

請求	使用 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。撤銷不會動到該金鑰部署過的執行個體；它們會繼續執行、繼續計費，直到你把它們停止或銷毀。

建立金鑰​

金鑰能做什麼​

列出金鑰​

撤銷金鑰​

建立金鑰

金鑰能做什麼

列出金鑰

撤銷金鑰