API 金鑰

開啟控制台 → API 金鑰，選擇權限組合或自訂 scopes，並複製產生的密鑰。密鑰只會顯示一次。

所有 API 路徑都會檢查 scope。金鑰只能存取其 scope 允許的範圍，而且僅限已正式開放給 API 的路徑。

• catalog:read: 瀏覽 GPU 與可用機器
• instances:read: 列出與讀取執行個體、資源用量、狀態、事件、執行紀錄與日誌
• instances:create: 部署自動化
• instances:manage: 停止、刪除、重啟與重新設定
• instances:exec: 在容器內執行指令——請見下方說明
• ports:manage: HTTP 連接埠與 raw TCP/UDP exposure
• vault:read / vault:write: 瀏覽與下載／上傳、重新命名與刪除
• billing:read: 付款紀錄與帳務設定
• org:read / org:manage: 讀取團隊／管理成員與設定
• notifications:read: 讀取與標記通知
• reservations:manage: 排隊預約
• tickets:manage: 開立客服單
• profile:read / profile:manage: 讀取帳戶／變更偏好設定（名稱、語系、通知設定）
• keys:manage: API 金鑰管理

「上傳權杖」組合只授予 vault:write。不需啟動任何執行個體，就能透過 HTTPS 寫入 /vault，讓腳本或 CI 直接推送資料集。

它刻意設計為唯寫，因為 CI 是憑證最不受信任的存放位置。從那裡外洩的權杖無法部署執行個體、無法啟動 GPU 花費，也讀不到、下載不了任何一個檔案——能存取 GET /vault/list 與 GET /vault/download-zip 的是 vault:read，而這個組合並不包含它。

curl -X POST "https://upload.gputw.ai/api/vault/upload?path=datasets" \
  -H "Authorization: Bearer gputw_live_..." \
  -F "[email protected]"

如上例，請將上傳送往傳輸主機：它直接連到儲存空間，不經過 CDN，因此單一請求沒有 100 MB 上限。同一個路由在主網域也能用，但會受該上限限制。超過 90 MB 的檔案請改用可續傳的分段上傳 API。詳見 Vault 儲存空間。

唯一需要讀取 session 的路徑——續傳與等待合併用的 GET /vault/uploads/<id>——同時接受兩種 vault scope，因此唯寫權杖仍能完成自己發起的上傳。完整上傳流程與 SCP 替代方案請見 Vault 儲存空間。

部分操作無論金鑰擁有哪些 scope 都無法使用，因為沒有任何 scope 能讓它們適合自動化。請改用瀏覽器登入操作。

• SSH 金鑰: 新增金鑰等同取得帳號下所有執行中執行個體的 root SSH 權限，會繞過金鑰原本的 scope 限制
• 帳戶安全設定: 變更密碼、變更 Email 與刪除帳號
• 建立與刪除團隊: 不可逆，且沒有自動化需求
• 結帳付款: 涉及金流，且需要互動式轉導
• 管理員 API: 一律不開放給使用者 API 金鑰

若金鑰外洩，請立即輪替。撤銷金鑰會停止後續 API 存取，但不會影響瀏覽器登入狀態。

請使用符合自動化需求的最小 scope。部署機器人通常需要 catalog:read、instances:read 與 instances:create。只讀取用量的監控程式僅需 instances:read。會停止、重啟或刪除執行個體的操作腳本需要 instances:manage。