跳至主要內容

驗證

本節記載的每個端點，除了 GET /v1/health 之外，都需要 bearer token：

Authorization: Bearer <token>

兩種憑證​

同一個標頭接受兩種憑證類型，而它們能觸及的範圍並不相同。

工作階段權杖API 金鑰
長什麼樣你登入主控台時簽發的 JWTshk_ 後面接 48 個十六進位字元
從哪裡來瀏覽器工作階段，會自動更新在主控台的 API 金鑰 頁面建立一次
有效期短期；會過期並更新直到你撤銷為止
以什麼角色運作你在組織中的真實角色，admin 或 member永遠是 member
組織你選擇的那一個只有金鑰被建立時所屬的組織
帳號端點（/v1/me、/v1/ssh-keys）允許以 401 TOKEN_INVALID 拒絕
管理員動作，含計費若你是管理員則允許以 403 ADMIN_REQUIRED 拒絕

任何無人看管執行的東西都請用 API 金鑰。工作階段權杖會過期，所以帶著它的腳本會毫無預警地停止運作。建立與撤銷的方式請參閱 API 金鑰。

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

選擇組織​

執行個體、範本、餘額與金鑰都屬於某個組織。X-Org-Id 標頭決定請求要在哪一個組織下執行：

標頭工作階段權杖API 金鑰
未帶你的個人組織金鑰自己的組織
設為你所屬的組織該組織，並套用你在其中的角色只有與金鑰的組織相符時才允許
設為你不屬於的組織403 NOT_A_MEMBER403 ORG_MISMATCH
不是有效的 id400 INVALID_ORG_ID403 ORG_MISMATCH —— 金鑰會先拿標頭跟自己的組織 id 比對，才去驗證它
curl -s "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY" \
  -H "X-Org-Id: 9c1b7d4e-3a52-4a1f-8c6d-b0e9f2a71c48"

用 GET /v1/orgs 列出你可以操作的組織，它會回傳每個組織的 id、name、personal 旗標、你的 role 以及餘額。這個呼叫需要工作階段權杖。

失敗情況​

狀態代碼意義
401TOKEN_INVALID缺少標頭、權杖格式錯誤、未知或已撤銷的 API 金鑰，或是把 API 金鑰送到帳號端點
401TOKEN_EXPIRED工作階段權杖已過期 —— 請重新登入
403NOT_A_MEMBERX-Org-Id 指的組織不是你的其中之一
403ORG_MISMATCHAPI 金鑰所屬的組織與 X-Org-Id 不同
403ADMIN_REQUIRED該動作僅限管理員，或你用 API 金鑰嘗試了它
400INVALID_ORG_ID在工作階段權杖的請求上，X-Org-Id 不是有效的 id

完整的回應格式在錯誤。

把金鑰當成密碼看待

任何持有 shk_ 金鑰的人，都能部署執行個體並花掉你組織的餘額。金鑰不要放進版本控制，而且只要你把金鑰貼到了你控制不了的地方，就撤銷它。