認證與 Base URL

Base URL

幾乎所有前端 sandbox 端點都在：


{TEAMSYNC_API_BASE}/private/module/sandbox

（注意是單數 module。）本手冊之後的租戶路徑省略這段前綴，例如「GET /settings」= GET {BASE}/private/module/sandbox/settings。

例外 — 沒有 /private 前綴，也不必登入： GET /public/info/sandbox/regions 與 GET /public/info/sandbox/profiles。不要把它們掛在 /private/module/sandbox 底下。

認證方式

帶標準 TeamSync 認證。get_current_user 再交給 get_sandbox_principal 解析行為主體。

Header	何時
`Authorization: Bearer <jwt>`	使用者登入（OAuth2 password bearer）。
`X-Api-Key: <key>`	API key。`get_current_user` 本來就吃這個 header。Sandbox 再讀一次以附上 scope／fingerprint／允許的房間。

兩者擇一。兩個都沒有 → 共用的 credential 例外，狀態碼是 418（Could not validate credentials，帶 WWW-Authenticate: Bearer），不是 401、也不是 sandbox 的 404。用戶端的重新登入／換 token 判斷必須認 418，只認 401 永遠不會觸發。API key 還會對照 key 的 domains 檢查 origin，除非 domain 清單含有單獨的 *。

後端用 get_sandbox_principal 解析出 principal：

欄位	值
`auth_method`	`jwt`（使用者登入）或 `api_key`
`principal_type`	`user` 或 `social_media_client`
攜帶	`company_id`、`role`、`api_key_scope`、`allowed_chatroom_ids`…

API key scope 的重要限制

Sandbox scope 的 API key 是「受限 key」，只允許：聊天室 menu、手動提交、查自己的 run（list/status/content/artifacts/download）、取消自己的 run。

受限金鑰不能用的管理面：quick-run、retry、environments（含 context 上傳）、tasks（含公司執行歷史）、granted-jobs、bindings、secrets、settings、root。要用這些，需要使用者 JWT 或 Full scope 的 key（Full 仍受租戶/角色限制）。

**狀態碼：**第一道 auth 閘門對 Quick Run、環境／任務管理、缺少 room path 或超出 key allowlist 的房間回 403（作者上傳 handle 保留明確 404）。有 room path 卻被 Sandbox route registry 排除的路徑，例如 retry、granted-jobs，回 405；受限 principal 若進到拒絕它的 Sandbox router 則回 404。這些回應不授予改走其他路徑的權限。

權限（角色）

誰能變更什麼，取決於 owner scope、consumer scope 與 聊天室管理員階梯，不是「凡是變更都要 company manager」。

環境異動依 owner scope 要求公司或擁有部門的管理權；GET/PUT /settings 仍限定公司管理員（role ≥ 3）。
建立目錄任務：公司擁有 → 公司管理員；部門擁有 → 該部門管理員（或公司管理員）。POST /tasks 送 owner_scope=chatroom 是 422。 呼叫者不能擁有的 department／company scope 回 403 owner_scope_forbidden。
房間啟用、綁定、secret、quick-run 走聊天室／consumer 階梯；部門管理員不能對別的部門的室硬啟用。分享 vs 啟用見任務受眾。
未授權的識別碼通常回 404，不洩漏資源是否存在。所以看到 404 常常是「沒權限」而不是「不存在」。

完整矩陣見角色與權限。

Kill switch → 503

SANDBOX_ENABLED 預設 true。設成 false 時：所有非 GET 的變更回 503 sandbox_disabled；例外是路徑以 /cancel 或 /download 結尾者仍可用。GET/HEAD/OPTIONS 一律放行。

Idempotency-Key（提交類必帶）

以下端點必須帶 Idempotency-Key header，否則回 422 idempotency_key_required：

POST /chatrooms/{id}/runs（提交執行）
POST /chatrooms/{id}/runs/{run_id}/retry
POST /chatrooms/{id}/quick-run
POST /secrets、/secrets/rotate、/secrets/revoke

規則（MAX_IDEMPOTENCY_KEY_CHARS = 128）：strip 後非空、≤128 字元、禁 NUL。客戶端用 UUID 很好，但伺服器不要求 UUID 語法。同一把 key 重送會回同一結果（安全重試）。每次新意圖換一把新 key。

請求 body 規則

所有請求 body 為 extra="forbid"：帶了未知欄位 → 422。
提交執行有先於讀 body 的大小防護：Content-Length 過大 → 413 request_too_large。

下一步：五分鐘跑一次。