Skip to Content
快速開始驗證與基底網址

驗證與 API 基底網址

Token 從哪裡來

這份快速入門使用的 scoped private API 以 TeamSync 登入 JWT 驗證。前端應沿用應用程式既有登入流程回傳並保存於執行階段的 access_token，不要為文件網站另做一套登入，也不要把 token 寫死在原始碼、測試資料、curl 檔案或版本控制中的環境檔。

Token 代表目前登入使用者；能不能操作某張表，還會由範圍與 ACL繼續判斷。換句話說，有合法 JWT 不等於擁有每一個端點的權限。

僅限 staging、且部署有開啟時：bearer 值 test-token 以 test company 的 admin user 身分行動，帶有 0 到 4 之間 role 的 test-token:<role> 則以該公司中擁有該 role 的 user 身分行動。在其他環境中，同樣的字串就只是無效的 JWT（418）。

Authorization header

這份入門中的 scoped private API 請求都把 JWT 放在標準 Bearer header：

Authorization: Bearer <JWT_FROM_APP_LOGIN>

在前端 request wrapper 中，header 會像這樣組成：

const response = await fetch(url, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})

curl 範例則從目前 shell 的 TOKEN 變數讀取，不把值留在文件或腳本裡：

curl "$BASE_URL/private/module/custom_tables/company/tables" \
  --header "Authorization: Bearer $TOKEN"

各介面接受哪種憑證

JWT 是 scoped Custom Tables 路由（包含資料表標籤路由）所用的憑證。其他憑證不能取代它：

  • 整合 API key（x-api-key header）。 對 Custom Tables 而言，整合 key 只能到達能力探索 GET …/core/capabilities：third_party key 在三種 scope 都可以，specific_chatroom key 則限於它清單中的房間（見範圍與掛載路徑）。其他每一條路由都拒絕這把 key，這兩種 scope 回 405（舊版 full scope 的 key 已不再簽發，是唯一的例外）。Custom Tables 的 input、artifact 與 package 路由（…/core/input-*、…/core/artifacts、…/packages）對這些 key 回 403 Access denied, invalid scope，而不是 405。另一種獨立的 work_calendar_read scope 的 key 只能到達兩條工作日行事曆 GET 路由，不能做能力探索（見工作日行事曆）；在這兩條路由上，third_party、specific_chatroom 或舊版 full key 都回 403 Access denied, invalid scope，而不是 405。
  • Command 與 command composer 只接受 JWT。API key 會被拒絕：舊版 full key 回 403 Custom-table command routes require JWT authentication；其他每一種 scope 則在路由執行前就被 scope gate 擋下（405，sandbox key 則是 403）。Composer 的 WebSocket 通道則改用 POST /private/get_signature/{chatroom_id} 取得的 signature 驗證。兩條 …/agent/commands/{command_id}/execute 與 /query 路由使用伺服器端的 service token，它不是 client 憑證。
  • OAuth access token（tsp_at_…）。 只有 MCP server 接受（見 Agent 工具箱）。在任何 REST 路由上，它都是 418。
  • Root token。 /root 底下的維運路由絕不接受 JWT，而是從標頭讀取 token。每一條 /root 路由都需要 X-ADMIN-TOKEN；SuperRoot 路由另外還需要 X-SUPER-TOKEN，CloudManager 路由（資料表清除、hotfix/custom-table-* 系列等）則另外還需要 X-SUPER-TOKEN 與 X-CLOUD-TOKEN。token 缺少或錯誤是 403。Root 維運操作有涉及 Custom Tables 的維運路由卡片。
  • 公開路由。 public-read token 是 URL 上的 id 加上 Bearer secret（除非該 token 是無 secret 建立的）；callback token 是 Bearer secret，或帶時間戳的 HMAC 簽章（x-callback-signature 與 x-callback-timestamp）；分段上傳的每個 chunk 由它的 session_id 授權。它們都不接受 JWT，而未知、已撤銷、已過期或驗證失敗的 read 或 callback token，回的永遠是同一個 404。

每一條 private 路由都可能回傳的錯誤列出各種憑證可能遭到的拒絕回應。

每一條 private 路由都可能回傳的錯誤

在本站有記載的 private 路由上，共用的驗證會先於任何路由專屬的閘門執行，唯一的例外是兩條 command-service 的 agent 路由，它們以自己的 service token 驗證。所以這些回應可能出現在 reference card 上的錯誤之前，而且沒有任何一個會被轉成資料表的 404。Body 是 {"detail": "<string>"}。API key 的到期與來源檢查（403 API Key expired、403 Access denied (API Key)）屬於 API key 管理，這裡不列出。

狀態detail原因
418Could not validate credentials沒有憑證（Authorization 用的若不是 Bearer scheme，視同沒有）；未知的 x-api-key，或擁有者已被刪除的 key；格式錯誤、簽章錯誤或已過期的 JWT；在 REST 路由上使用 OAuth tsp_at_… token。回應帶有 WWW-Authenticate: Bearer。它是 418，不是 401。
404Could not validate credentials (username) not foundJWT 簽章有效，但沒有 sub 或沒有 company_id claim，例如把重設密碼的 ticket 當成 bearer token 使用。
404User not foundJWT 指名的 user 在它所屬的公司中不存在。
405Access to <METHOD> <path> is not allowed for your role整合 key 用在其 scope 的 allowlist 以外的路由。
403Access denied, invalid scopescope gate 直接拒絕這把 key，沒有 allowlist 的回應。出現在工作日行事曆路由：third_party、specific_chatroom 或舊版 full key 打任一條 GET，以及 work_calendar_read key 打 PUT。
403Access to chatroom <chatroom_id> is not allowed for this API keyspecific_chatroom 或 sandbox key 的請求對象是不在其清單中的房間。
403This API key has no allowed chatrooms configured房間清單為空的 specific_chatroom key，用在房間路由上。
451、401、409、410Account expired、Account not verified yet、Account disabled、Account deleted帳號的到期日已過（role -2 不受此限），或帳號尚未驗證、已停用或已刪除。

API 基底網址

環境基底網址用途
Staginghttps://api.scfg.io本站範例與工具的預設環境
自訂環境由你的團隊提供可在本站工具的 Base URL 欄位覆寫

組合請求時，直接把 catalog 顯示的完整路徑接在基底網址後面。例如 staging 的公司層級資料表清單是 https://api.scfg.io/private/module/custom_tables/company/tables。

準備好 JWT 後，可以先到 API Playground確認驗證，再進行第一張資料表的五次呼叫。

Last updated on
開始使用範圍與掛載路徑