Skip to Content
快速開始認證與 Base URL

認證與 Base URL

Base URL

所有前端 sandbox 端點都在：

{TEAMSYNC_API_BASE}/private/module/sandbox

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

認證方式

帶標準 TeamSync 認證。後端用 get_sandbox_principal 解析出 principal：

欄位值
auth_methodjwt（使用者登入）或 api_key
principal_typeuser 或 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。

以下對受限 key 一律 404：quick-run、retry、environments、tasks、bindings、secrets、settings、root。要用這些，需要使用者 JWT 或 Full scope 的 key（Full 仍受租戶/角色限制）。

權限（角色）

  • 變更類（建環境/任務、改設定、綁定、secret）需要 company manager（RoleRequired(3)）。
  • 未授權一律回 404，不洩漏資源是否存在。所以看到 404 常常是「沒權限」而不是「不存在」。

Kill switch → 503

當 SANDBOX_ENABLED=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

同一把 key 重送會回同一結果（安全重試）。前端每次「新的意圖」用一把新的 UUID；重試時沿用同一把。

請求 body 規則

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

下一步：五分鐘跑一次。

Last updated on
總覽五分鐘跑一次