讓外部系統以回呼寫入資料列

情境：ERP 每收到一張新訂單，就要直接寫進聊天室的訂單表，而不持有任何使用者 access token。

前置條件

table moderator 才能 mint 與 revoke callback token；外部系統只需要 mint 回應中的 token_id 與一次性 secret。本例使用聊天室 11111111-1111-4111-8111-111111111111 與資料表 22222222-2222-4222-8222-222222222222。private 管理請求使用使用者 access token，public write 則使用 callback secret。

步驟

1. Mint 最小權限 token

透過 callbackTokens.mint 建立憑證時，若只新增資料列，將 allowed_ops 設為 create；只有確定整合也要按 record ID 更新時，才使用 create,update。到期時間要配合可實際執行的輪替週期。

POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/callback-tokens
Content-Type: application/json
 
{
  "name": "ERP 訂單匯入",
  "allowed_ops": "create",
  "valid_until": "2026-08-01T00:00:00Z"
}

回應只在這一次包含 secret。立即交給 secret manager，並分開保存 token_id；不要把回應寫進 application log、ticket、分析事件或原始碼。之後的 token list 不會幫你取回 secret；遺失時應 mint 新 token。

2. 從外部系統 POST 一筆資料

呼叫 callback.write 時，token_id 放在路徑，secret 放在 Bearer header。data 使用資料表顯示欄名；idempotency_key 應使用來源事件的穩定唯一 ID，讓 24 小時內的網路重試重播原結果而不重複寫入。

curl -X POST \
  -H "Authorization: Bearer <one-time-secret>" \
  -H "Content-Type: application/json" \
  --data '{
    "op": "create",
    "data": {
      "訂單編號": "ORD-1042",
      "數量": 3
    },
    "idempotency_key": "erp-order-created-1042"
  }' \
  "https://api.example.invalid/public/module/custom_tables/callback/33333333-3333-4333-8333-333333333333"

成功建立時保存回應的 record_id。若 replayed 是 true，代表這次重試沒有新增第二筆。若表格規則要求核准，status: "held_for_approval" 會提供 process_id 與 staged_change_id；這是已接受的 terminal success，資料仍在核准流程中，不要重送 callback。

3. 在整合邊界強制安全限制

每個 callback request 的原始 body 上限是 65,536 bytes；一個事件送一筆、不要把它當 bulk import。token 固定綁定單一 table 與 allowed_ops，不是通用使用者 Bearer token。只透過 TLS 傳送、對 secret 做 log redaction，並監控拒絕與限流比率，但不要記錄 header。

輪替時先 mint 新 token、更新外部 secret、以新 token 完成一筆 idempotent probe，最後才 revoke 舊 token。

4. 完成或停用整合時 revoke

callbackTokens.revoke 使用 private scope path 與 token_id，不需要也不應再傳 secret。

DELETE /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/callback-tokens/33333333-3333-4333-8333-333333333333

revoke 後停止所有 sender retry，並從 secret manager 刪除舊 secret。public endpoint 對無效、過期或 revoked token 使用一致的 not-found 行為，因此不要靠錯誤差異判斷 token 是否存在。

你會看到什麼

mint 回應會出現一次性的 secret；第一個 callback 回應會是 status: "created" 與新 record_id；以相同 idempotency key 重試會是 replayed: true。revoke 後舊憑證不再能建立資料列。

常見錯誤

請直接查看mint 錯誤表、public write 錯誤表與revoke 錯誤表。

試試看

用 API Playground 執行 callbackTokens.mint 與 callbackTokens.revoke；public callback 請用上面的 curl 從受控測試 sender 發送，並確認 client 沒有記錄 Authorization header。