變更紀錄

本頁記錄對外契約的變更。棄用至少 90 天前公告（見版本與棄用）。

目前契約版本：1.0.0-draft

來源 commit：a9c0c2b0d98ae51c74169dbb981d17fb694ab107

1.0.0-draft（2026-09-23 修訂）

契約草案在審查後的修訂，版本號未變（仍是尚未發布的草案）。

• 新增 POST https://auth.lightup.tech/oauth2/token 到契約。 取 token 不再只是文字說明：request（三種 grant 的 oneOf）、回應與四個 OAuth 錯誤碼都在 schema 裡，本文件的「取 token」段落由它產生。注意這個端點不在 API host 上，也沒有 /v1 前綴。
• 寫入的前置條件收緊成 RFC 9110 標準語意。 建立用 If-None-Match: *、更新用 If-Match: "<etag>"，恰好擇一；兩個都不帶或都帶是新的 428 precondition_required。沒有「無條件覆寫」這個操作。
• 錯誤代碼異動：新增 already_exists（用 If-None-Match: * 建立但已存在）與 precondition_required；移除 if_match_required。所有衝突都是 409，本 API 不使用 412。
• Problem.error 收斂成封閉集合。 401 一律 invalid_token（不細分，細分等於幫人確認哪一項錯）；403 是一組逐字來自授權決定的 deny 代碼（新增 client_unknown／client_disabled／actor_unknown／client_not_third_party／profile_not_supported／subject_revoked／epoch_changed／capability_not_in_token／capability_unavailable／resource_type_mismatch／tenant_mismatch／no_relationship，取代舊的 insufficient_scope 與 resource_policy_denied）＋兜底 forbidden；503 分成 authorization_unavailable 與 token_verification_unavailable。完整清單見錯誤・限流・重試，那一頁由契約產生，不在這裡重抄數量。
• 新增 403 tenant_suspended。 租戶被停權時所有第三方存取都停，與呼叫端是誰、要哪一項能力無關；重試與換 token 都沒有用。它不折成 404（即使打在 person 資源上），因為它講的是你的租戶而不是目標資源存不存在。
• GET /v1/tenant 拿掉 state。 v1 只回識別欄位（tenantId、displayName），不回營運狀態：停權租戶的 token 在簽發與每次判權兩處就已經被擋，狀態會以 401／403 出現，而不是以一個要自己判讀的欄位出現；Gateway 也不會在上游沒給值時猜一個 active。
• tenant_mismatch 與 no_relationship 打在 person 資源上時回 404。 否則 403 與 404 的差別本身就是一支「這個 person 存不存在」的探測器。
• delegated 與 shared profile 是 403 profile_not_supported，不是 401。 它們簽章是對的，由授權端拒。
• 文件網站網域定案：developers.lightup.tech（Steven，2026-09-23）。本文件的所有位址至此全部有實際值，不再有佔位符。但端點仍未開放：api.lightup.tech 目前不接受請求，啟用日期另行公告。
• 對外 API host 定案：api.lightup.tech（Steven，2026-09-23）。該網域先前沒有 ingress，是分配給第三方 Gateway 的閒置網域，不是接管誰的入口；LightUp 第一方 App 維持 api.app.lightup.tech、後台維持 api.d.lightup.tech，都不受影響。這推翻了本契約較早版本寫的「不可用 api.lightup.tech」——那句話依據的部署檔在這一點上是錯的。文件網站的網域仍未定案。
• 待定位址改成機器可讀。 server URL 從 api.lightup.tech 改成正式的 OpenAPI server variable https://{host}/v1，並帶 x-lightup-status: pending-host。候選值是 partners.lightup.tech，定案前不得當成可用網址；這個標記還在，文件包就不得對外發布。

1.0.0-draft

狀態：Proposed（草案）。此版本描述的端點尚未上線。

首次發布的對外契約草案。

• 定義 /v1 的七個操作：GET /v1/me、GET /v1/tenant、GET /v1/persons/{personId}，以及 person extension 的列表、讀取、寫入與刪除。
• 定義兩種授權模式：client_credentials（profile workload，主體是 service account）與 authorization code + PKCE（profile self，主體是使用者）。
• 定義 token 驗證契約：ES256、固定 JWKS、aud = lightup-api、JOSE typ = at+jwt、TTL 15 分。
• 定義能力目錄（五項，全部 preview）與 lightup.<capability> scope 命名空間。
• 定義撤權語意：下一個請求生效，v1 無 allow-cache；不承諾秒數（待實測）。
• 定義錯誤語意：穩定 error 代碼、每個回應都有 x-request-id、403 與 503 嚴格分開。
• 定義 person extension 的 revision／If-Match、額度與匯出刪除途徑。

已知的待定項