登記與憑證
第三方應用要能呼叫 API，需要三樣東西：應用（application）、client、service account（只有機器流程需要）。
誰做什麼
| 角色 | 做什麼 |
|---|---|
| 發布者（你） | 提供應用名稱、用途、redirect URI、要用的能力清單、聯絡窗口 |
| 平台團隊 | 配發 client id、建立 client 與 service account、交付憑證 |
| 租戶管理員 | 在 LightUp Dashboard 的「整合」頁核准這支應用的能力集合、停用、輪替、查用量 |
Dashboard 的「整合」頁尚未提供。 在它上線之前，登記與核准由平台團隊以人工流程處理；請透過既有的支援窗口提出，附上下面「登記需要的資料」。這一段會在 Dashboard 頁面上線後更新。
Client
- client id 由平台配發，形狀
tp_<租戶標籤>_<slug>，全域唯一。不接受自選字串直接寫入。 - 第三方 client 有幾條硬性限制，註冊時就會被拒，不是默默忽略：
- redirect URI 一律精確比對；不支援子網域萬用字元。public client 另外允許 loopback（RFC 8252 §7.3）。
- 不得使用
native_credentialgrant、web handoff，或任何 refresh 放寬（reuse grace／sliding／absolute-max 一律視為 0）。 - 不得標記為平台第一方。
- 同一支應用可以同時有互動（使用者）與背景（機器）授權，但兩者必須分開可辨認。互動授權失敗不可以改用背景憑證完成同一個操作。
Service account（機器流程）
- 主體是 service account，不是 client。client 憑證證明「哪支程式」，service account 才是「誰在平台裡做事」，id 形狀
acc_…。 - 每個租戶為每一項整合建立可獨立停用的 service account。不共用一張跨租戶的高權限帳號。
- 憑證輪替：建立
nextsecret → 兩把並存最長 7 天 → promote（next變current，舊的立即失效）。兩把並存期間，平台分別記錄哪一把被用到，所以輪替是可驗收的，不是盲切。 - 撤銷：停用帳號，或推進 actor epoch。在途 token 在下一個請求就失效（見撤權語意）。
登記需要的資料
| 欄位 | 說明 |
|---|---|
| 應用名稱與發布者 | 會顯示在使用者同意頁上 |
| 用途說明 | 一句話說明這支應用拿這些資料做什麼 |
| 能力清單 | 從能力索引挑，逐項列出，不要寫「全部」 |
| Client 型態 | public（行動／桌面／SPA，強制 PKCE）或 confidential（有伺服器端） |
| Redirect URI | 精確值，逐一列出；只有使用者流程需要 |
| 技術窗口 | 處理撤權、輪替、事故通知 |
| extension 需求 | 若要寫 metadata，說明用途、欄位與預估筆數（見 Metadata） |
憑證的保管
- client secret 與 service account secret 只在伺服器端保存。行動 App 與瀏覽器前端不得內嵌任何機器憑證——要代表使用者，就走 authorization code + PKCE。
- 不要把憑證放進版本控制、log、錯誤回報或本文件的範例設定檔。範例用的
.env.example只有合成值。 - 懷疑外洩：立刻要求撤銷（停用帳號或推進 epoch），再輪替。撤銷在下一個請求生效，不必等 token 過期。