API 金鑰

API 金鑰是你交給腳本、CI 工作或自家工具的憑證。它以某個組織成員的身分進行驗證，沒有到期日——不過，personal 金鑰會在它的建立者離開組織時失效。

建立金鑰

在主控台開啟 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": "local-scripts", "kind": "personal"}'

欄位	型別	備註
`name`	字串，1–64 個字元	必填。金鑰在主控台中的標示方式。
`kind`	`personal` 或 `team`	預設為 `personal`。`team` 金鑰由管理員管理，需要管理員的工作階段才能建立。

依照這個憑證該歸誰所有來選擇類型。personal 金鑰跟你綁在一起：你可以自己撤銷它，而你一旦被移出組織，它就會被自動撤銷。team 金鑰屬於組織，建立者離開後仍然有效。CI 管線和其他共用的自動化請用團隊金鑰，否則它們會在建立者被移除的當天停止運作。請見角色與權限。

回應會回傳金鑰的中繼資料與密鑰：

{
  "key": {
    "id": "0f5a1c93-6d21-4e7c-a0b8-3c9f2e1d4a77",
    "name": "local-scripts",
    "kind": "personal",
    "prefix": "shk_9f3a21c4",
    "creator_email": "you@example.com",
    "creator_id": "7c2e9a41-5b0d-4f3e-8a16-d94b2c07e5f1",
    "created_at": "2026-07-24T11:02:44.318Z",
    "last_used_at": null,
    "creator_is_member": true
  },
  "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。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。金鑰會在它下一次發出請求時失效。在主控台中，金鑰旁的垃圾桶圖示會先詢問，並指明是哪一把金鑰、它是個人金鑰還是團隊金鑰；按 撤銷金鑰 確認。

誰	可以撤銷
管理員	組織中的任何金鑰
成員	只有自己的 `personal` 金鑰
API 金鑰	什麼都不行 —— `403 ADMIN_REQUIRED`

撤銷未知的、已撤銷的，或屬於別的組織的金鑰，會回傳 404 API_KEY_NOT_FOUND。撤銷不會動到該金鑰部署過的執行個體；它們會繼續執行、繼續計費，直到你把它們停止或銷毀。

建立金鑰​

金鑰能做什麼​

列出金鑰​

撤銷金鑰​

建立金鑰

金鑰能做什麼

列出金鑰

撤銷金鑰