撤權語意

承諾

撤權在下一個請求生效。

因為 Gateway 每個請求都向身分服務查一次當前授權，沒有跨請求的 allow-cache，所以撤權不需要等 token 過期。

目前不對外承諾任何秒數。 最大傳播時間要在真實隔離部署上實測後才會公布；在那之前，本文件只承諾「下一個請求生效」這件事本身。任何看到的數字都是內部設計目標，不是 SLA。

Token 自身過期

TTL 是上限，不是撤權機制。不要拿「反正 15 分鐘就過期」當作撤權已經生效的理由——撤權比它早，而且與它無關。

你這端要做什麼

• 拿到 401：重新取 token 再試一次。還是 401 就停止，並通知你的營運窗口——這通常表示 client 或 service account 被停用。
• 拿到 403：不要重試。重試不會變成允許。看 error 代碼判斷去修哪裡—— client_disabled（整合被停用）、subject_revoked（帳號或 session 被撤銷）、 epoch_changed（帳號被撤權過，換一張 token）、capability_not_granted（沒授權）、 plan_capability_excluded（方案不含）。
• tenant_suspended 是租戶層級的停權：與呼叫端是誰、請求哪一項能力都無關，整個租戶的第三方存取都停，讀寫皆然。換一張 token 也一樣被拒（簽發端同樣會拒），要等租戶恢復。
• 撤權是 403，不是 401。 被停用的 client 送出的 token 仍然簽得好好的、也還沒過期， 所以擋它的是授權那一段。把它當成 401 去換新 token 沒有用——新 token 一樣被擋。
• 使用者撤銷授權後，你這端保存的 refresh token 會失效。要能優雅地把使用者導回重新授權，而不是卡在錯誤畫面。
• 背景工作要能中途被拒：一批同步做到一半被撤權是正常情況，要能記錄進度、安全中止，而不是重跑整批。

平台收不回的東西

平台無法收回第三方已經取得的資料副本。撤權擋的是之後的請求，不是你已經寫進自己資料庫的內容。你自己那一份的保留、刪除與匯出，由你的安全與產品契約決定。

同樣地，檔案 URL、下載連結與各種快取有各自的生命週期；不要假設撤權會讓一個已經發出去的 URL 立刻失效。