變更紀錄
本頁記錄對外契約的變更。棄用至少 90 天前公告(見版本與棄用)。
目前契約版本:1.0.0
來源 commit:707394544381e2463650e138e6a62174e06c9861
1.0.0(2026-11-06:流量報表轉為預覽)
契約版本仍是 1.0.0。 新增操作不升版(見版本與棄用)。
lightup.analytics.traffic.read由規劃轉為預覽,新增GET /v1/analytics/traffic/query與GET /v1/analytics/traffic/metrics,見報表數字。其他報表能力仍是規劃中。
1.0.0(2026-11-06:報表能力依領域拆開)
契約版本仍是 1.0.0。 新增規劃中的能力不升版(見版本與棄用)。
- 規劃中的
lightup.analytics.read改成 9 項,依報表領域各一項:營收、流量、廣告、顧客、訊息、客服、點數與會員、課程、互動。都還是planned:還不能核准、不能取得 token,也沒有路由。
1.0.0(2026-10-30:公布完整能力目錄,79 項規劃中)
契約版本仍是 1.0.0。 新增規劃中的能力不升版(見版本與棄用)。
- 能力目錄一次列出平台打算開放的全部範圍:顧客與身分(聯絡方式、查詢、清單、寫入、監護、行銷同意、分眾)、會員與點數、優惠券、商品與庫存、訂單清單與退款、發票、付款、訂閱、課程、預約、表單、LINE 與統一發送、email 範本、排程發送、客服對話、行事曆、檔案、短網址、任務、前台頁面、自動化流程、會計帳、報表與設定。見能力索引。
- 這 79 項全部是
planned(規劃):還不能核准、不能取得 token,也沒有路由。每一項轉為預覽時,會在這裡公告端點與欄位。 - 全部只限機器流程,資源是租戶,方案 L2 起。
1.0.0(2026-10-28:新增客戶的被監護人能力,預覽)
契約版本仍是 1.0.0。 新增操作不升版(見版本與棄用);新增的能力狀態為預覽,不適用正式版的支援與棄用保證。
- 能力目錄新增一項:
lightup.person.wards.read是preview(預覽)。資源是租戶,方案 L2 起,只限機器流程。見能力索引。 - OpenAPI 新增一個操作:
GET /v1/persons/{personId}/wards,一次查一位監護人(psn_person id 或訂單customerId的 UUID),列出他目前監護中的孩子,每個孩子帶personId與POST /v1/persons:profiles相同的五個欄位。只列生效中的關係,最多 50 個孩子,超過時回"truncated": true。見標籤與顧客。 - 部署完成之前仍是 404。 帶著這一項的發版部署完成之前,打這個操作回 404(路由還沒有掛上)。
- 「開全部」是當下的快照。 這次發版之前記錄的授權不會多出這一項;要用到它,租戶要重新核准。
- 沒有新的錯誤代碼。
1.0.0(2026-10-26:標籤寫入與建立標籤由規劃轉為預覽)
契約版本仍是 1.0.0。 能力目錄的狀態轉換不升版(見版本與棄用);兩項能力狀態為預覽,不適用正式版的支援與棄用保證。
lightup.tag.write、lightup.tag.define由planned(規劃)轉為preview(預覽)。 2026-10-19 提前公布的五個操作開始提供:PUT/DELETE /v1/persons/{personId}/tags/{tagId}、POST /v1/tags/{tagId}/members:add、:remove,以及POST /v1/tags。形狀與錯誤代碼都沒有變。資源是租戶,方案 L2 起,只限機器流程。見標籤與顧客。- 標籤成員的寫入在租戶的身分切換完成之前一律被拒:回 409
tag_writes_not_open。這是租戶的狀態,不是權限問題,重試、換 token 或重新核准都不會變;切換完成之前不要開始寫入標籤成員。建立標籤(POST /v1/tags)不受這個限制。 - 部署完成之前仍是 404。 帶著這兩項的發版部署完成之前,打這五個操作仍回 404(路由還沒有掛上)。
- 「開全部」是當下的快照。 這次發版之前記錄的授權(包括當時的「開全部」)不會多出這兩項;要用到它們,租戶要重新核准。之後新記錄的「開全部」會包含它們。
- 能力目錄裡已經沒有規劃中的能力:五項正式、十項預覽。
1.0.0(2026-10-25:新增客戶基本資料能力,預覽)
契約版本仍是 1.0.0。 新增操作不升版(見版本與棄用);新增的能力狀態為預覽,不適用正式版的支援與棄用保證。
- 能力目錄新增一項:
lightup.person.profile.read是preview(預覽)。資源是租戶,方案 L2 起,只限機器流程(client_credentials,workloadtoken)。見能力索引。 - OpenAPI 新增一個操作:
POST /v1/persons:profiles,以 1–500 個 id(舊客戶 UUID 或psn_person id)讀取客戶的givenName、familyName、displayName、birthDate、gender。只有FOUND帶這五個欄位,它們一定出現、沒有值時是null;沒有列出全部客戶的形式,也不回傳電話、email 或地址。見標籤與顧客。 - 名稱請準備好退回
displayName:新系統建立的孩子常常只有顯示名稱。 - 沒有新的錯誤代碼,錯誤對應與
POST /v1/persons:resolve相同。 - 「開全部」是當下的快照。 這次發版之前記錄的授權不會多出這一項;要用到它,租戶要重新核准。之後新記錄的「開全部」會包含它。
1.0.0(2026-10-19:新增標籤與顧客、LINE 訊息組能力,讀取為預覽、寫入為規劃)
契約版本仍是 1.0.0。 新增操作與新增錯誤代碼不升版(見版本與棄用);新增的讀取能力狀態為預覽,寫入能力狀態為規劃,尚未開放。
- 能力目錄新增五項:
lightup.tag.read、lightup.person.resolve、lightup.line.target是preview(預覽);lightup.tag.write、lightup.tag.define是planned(規劃)。全部的資源是租戶,方案 L2 起,只限機器流程(client_credentials,workloadtoken)。見能力索引。 - OpenAPI 新增十一個操作。 六個讀取(預覽):
GET /v1/tags/{tagId}/members、POST /v1/persons:tags、POST /v1/tags:lookup、POST /v1/categories:lookup、POST /v1/persons:resolve、POST /v1/line-targets。五個寫入(規劃,提前公布形狀;在轉為預覽之前不提供,路由不掛載、呼叫回 404):PUT/DELETE /v1/persons/{personId}/tags/{tagId}、POST /v1/tags/{tagId}/members:add、POST /v1/tags/{tagId}/members:remove、POST /v1/tags。見標籤與顧客(預覽)。 POST /v1/line-targets回傳 LINE user id:可以送的客戶(DELIVERABLE)會帶lineUserId,那是他在該租戶自己的 LINE 官方帳號下的 id。- 標籤成員寫入的
Idempotency-Key必須是 UUID(有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可),與建立訂單的規則不同。 GET /v1/tags/{tagId}/members只收after與limit:未知或重複的查詢參數是 422schema_invalid。- 新增錯誤代碼:
tag_writes_not_open、person_merged、tag_name_conflict(409),tag_limit_reached、category_not_found(422)。見錯誤・限流・重試。 - LINE 訊息組(預覽):能力目錄再新增
lightup.line.message_group.read(preview,資源是租戶,方案 L2 起,只限機器流程),OpenAPI 新增兩個操作:GET /v1/line-message-groups?name=…(以完整名稱查,最多 10 個,回matched/truncated;只收一個name參數)與GET /v1/line-message-groups/{groupId}。每則訊息只有type、complete與文字或媒體 id(不是網址);complete為false的訊息組不要送。沒有新的錯誤代碼。見LINE 訊息組(預覽)。 - 「開全部」是當下的快照。 這次發版之前記錄的授權不會多出這六項;要用到新的能力,租戶要重新核准。之後新記錄的授權(包括「開全部」)會包含四項預覽能力,不包含兩項規劃能力。
1.0.0(2026-10-17:新增訂單能力,預覽)
契約版本仍是 1.0.0。 新增操作與新增錯誤代碼不升版(見版本與棄用);新增的三項能力狀態為預覽,不適用正式版的支援與棄用保證。
- 能力目錄新增三項,全部是
preview(預覽):lightup.order.create、lightup.order.read、lightup.order.cancel。資源是租戶,方案 L2 起,只限機器流程(client_credentials,workloadtoken)。使用者本人的 token 會得到 403profile_not_supported。見能力索引。 - OpenAPI 新增三個操作:
POST /v1/orders(建立未付款訂單,Idempotency-Key必填)、GET /v1/orders/{orderId}(讀取)與POST /v1/orders/{orderId}/cancel(取消)。見訂單(預覽)。 - 新增請求標頭:
Idempotency-Key(建單必填,同一個 key 與同一份請求的重送回原來的訂單)與X-LightUp-Operator(選填,只是註記,不參與授權)。 - 新增錯誤代碼:
idempotency_key_reused、request_in_progress(409,後者帶Retry-After: 2)、order_not_cancellable(409)與product_unavailable(422)。Problem新增選填欄位detail,目前只有order_not_cancellable使用。見錯誤・限流・重試。 - 預覽不等於可以不看。 在轉為
ga之前,欄位與錯誤細節仍可能調整;轉為ga時會在本頁公告。
1.0.0(2026-10-05:正式版)
API 進入正式版:契約版本由 1.0.0-draft 改為 1.0.0,對外公開。 契約形狀沒有破壞性
變更;從這一版起,版本與棄用的相容政策(加欄位不升版、改語意升
/v2、棄用至少 90 天前公告)完整適用。
- 能力目錄五項全部由
preview轉為ga(正式)。lightup.profile.self.read、lightup.person.read、lightup.person.metadata.read、lightup.person.metadata.write、lightup.tenant.info.read。狀態轉換本身不算 API 升版;見能力索引。 - OpenAPI 新增登出端點
GET|POST https://auth.lightup.tech/oauth2/logout(RP-Initiated Logout,discovery 的end_session_endpoint)。這條端點自 2026-09-28 起 就已上線、行為也已寫在使用者流程;這次是把參數(id_token_hint必填、client_id、post_logout_redirect_uri、state)、確認頁與 200/302/400/ 404/503 各回應補進機器可讀的契約,行為沒有改變。 - 本站開放搜尋引擎收錄(拿掉
noindex)。
1.0.0-draft(2026-10-02:生效改由方案與租戶自助開關決定)
契約形狀沒有變更;變的是 tenant_not_enabled 背後的原因,以及誰能讓它消失。
- 平台不再維護逐租戶的開通名單。 一個租戶的第三方整合是否生效=方案含第三方整合
(business 以上) 且 租戶 owner 在 Dashboard「整合」頁打開了開關 且 平台沒有暫停
這個租戶。三個條件任一不成立,
/v1/*都是 403tenant_not_enabled、token 端點回invalid_client;對外不分辨是哪一個條件。 - 處理方式從「向 LightUp 申請」改成「找租戶管理員」。 方案不足時頁面會寫明;方案夠 的租戶由 owner 自己開,關閉也由 owner 自己關(下一個請求起生效,最長延遲約 30 秒)。
- 新增一種可重試的情況:503
authorization_unavailable。 當 Gateway 真的判不出租戶 狀態(讀不到開關)時回 503,而不是 403;這是暫時的,可以重試。403 仍然不可重試。 - 文件中所有「開通名單」「向 LightUp 申請」的說法已同步改寫:起步、 登記與憑證、撤權、 錯誤・限流・重試、支援。
1.0.0-draft(2026-09-30:端點開放)
端點已上線,本站的「尚未開放」提示同時撤下。契約形狀沒有任何變更,版本號未變。 以下是從「照契約開發」變成「可以真的呼叫」的那幾件事:
https://api.lightup.tech/v1開始接受請求。 第三方 Gateway 已部署,/v1的七個 操作都在線上。文件裡的每一段仍是同一份契約,差別只在它現在有一個會回答的環境。auth.lightup.tech的第三方端點全部上線:authorization_code+ PKCE 的登入、client_credentials、/oauth2/revoke、/oauth2/introspect、back-channel logout 與 RP-initiated logout。client_credentials也已經在 discovery 的grant_types_supported裡公告——機器流程先前寫的「尚未實作」已經不成立。- 生效是逐租戶的。 端點開放當天,哪些租戶可以用第三方 API 是平台這一側的名單;
2026-10-02 起改由租戶方案與租戶自助開關決定(見上一條)。租戶未生效時,
/v1/*每個呼叫都是 403tenant_not_enabled,token 端點也拒(invalid_client); 重試與換 token 都沒有用。 - Dashboard 的「整合」頁已上線。 登記應用(使用者登入/機器對機器/兩者)、維護 redirect、post-logout 與 back-channel 網址、核准與撤回能力、建立/輪替/停用/ 重新啟用 service account,都由租戶管理員自己完成,不再是人工流程。 見登記與憑證。
- introspect 對機器 token 一律
active: false(新寫進文件的限制)。client_credentials鑄出來的 service account token 沒有 session,而 introspection 的設計要求 token 背後有一顆活的 session,所以它對這種 token 一律回{"active": false}——即使那張 token 當下完全有效。機器端要判斷還有沒有權,權威來源 是 Gateway 的判權結果:打一次/v1/*,200 就是還有權,403(subject_revoked/epoch_changed/capability_not_granted)就是沒有了。 見機器流程與撤權語意。 - 撤權仍然只承諾「下一個請求生效」,不給秒數、沒有 SLA。 平台已經在真實環境量過, 但那是觀測值不是承諾,所以不寫進本文件,對外承諾維持不變。
- 能力目錄五項仍全部是
preview。 契約與實作都已定案並上線,但尚未適用ga的支援 與棄用保證;狀態轉ga時會在這一頁公告。
1.0.0-draft(2026-09-27 修訂)
登入面(OIDC)的錯誤形狀與 session 生命週期寫進契約,版本號未變。 來源是 Amygdala
的兩支 PR — lightup-rs #1408(第三方 OIDC 登入走租戶登入 v2、psn_ subject、
session 綁定 token)與 #1412(introspection、back-channel logout、RP-initiated
logout),以及 #1425(同租戶的第一方 logout 導回、封鎖 IPv4-compatible IPv6)。
✅ 三支都已合併並於 2026-09-30 上線(見最上方的條目)。本節寫下時它們還沒部署,現在是正式行為。
- token 端點新增機器可讀的
error_description(#1408,refresh 路徑由 #1412 延伸)。 租戶被停權時,authorization_code與refresh_token都會得到400 {"error":"invalid_grant","error_description":"tenant_suspended"}——RFC 6749 的 OAuth 錯誤形狀,不是 403Problem。tenant_suspended這個字串 從此出現在兩種形狀裡(簽發被拒 400 OAuth error/每請求判權被拒 403Problem), 解析路徑要分開。error_description的其他值仍然不保證穩定。回應可能帶一個message欄位,不是契約的一部分。 - 新增
POST https://auth.lightup.tech/oauth2/introspect(RFC 7662)到契約。 只有 已啟用的 confidential 第三方 client 可以呼叫、只能查自己的 token;非 active 一律{"active":false}(不分原因);讀不到或逾時是 503,絕不回active:true; 無快取。這是判斷 token 現在有不有效的權威來源。active:true的回應中,token_type對 access token 是Bearer(不是access_token)、對 refresh token 是refresh_token;sid是 32 個十六進位字元(不是 UUID);acr只會是urn:lightup:loa:1或urn:lightup:loa:2。 /oauth2/revoke的租戶以 client 登記的租戶為準(與 token 端點同一條解析), 不由redirect_uri的網域或請求參數決定。POST https://auth.lightup.tech/oauth2/revoke(RFC 7009)寫進契約,並把語意講清楚。 它只撤呼叫端這個 client 的 refresh token family,不結束使用者的登入、不送 back-channel logout。要把使用者登出請用/oauth2/logout。- refresh token 重放的後果加重且明文化。 重送一張已消耗的 refresh token 不只是
invalid_grant:整個 family 撤銷、綁定的整顆登入 session 結束、這顆 session 上 所有第三方 app 收到 back-channel logout。沒有 retry grace;逾時不確定時 請用 introspect 判斷,不要重送。 - logout 登記值的申請方式與規則。 post-logout redirect URI 與 back-channel logout URI
是一份旁掛登記值,由租戶 owner 在 Dashboard 送出或平台操作者用內部路由代填——
第三方不直接呼叫內部 API。每次送出是整份覆寫,省略即清空。URI 必須 https、
公開網域(網域必須含一個點,裸主機名會被拒)、無 fragment/wildcard/userinfo、
≤ 2048 字元,拒絕 IP(v4/v6)、
localhost、*.localhost、.local、.internal、.svc、.cluster.local;post-logout redirect URI 最多 10 個, 比對是精確字串。被拒時的代碼已定稿且穩定(不要對訊息文字做字串比對): 400too_many_uris(> 10 個)與 400invalid_uri(帶field、postLogoutRedirectUris另帶index、以及reason∈too_long(2048 位元組)/unparsable/not_https/wildcard/userinfo/fragment/ip_literal/private_host/not_fully_qualified); 404client_not_found(client 不存在或非第三方)與 404not_found(功能未開); 503temporarily_unavailable(讀寫失敗,可重試)。只回第一個不合規的 URI, 檢查順序固定,同時犯兩條時回先撞到的那一個。沒登記 back-channel URI 就收不到 back-channel logout; 沒登記 post-logout redirect URI,使用者登出後只會看到平台的「已登出」頁。 - back-channel logout 的定位:best effort,不是保證。 只有登記過的 app 收得到, 送信會重試但平台重啟可能遺失。不可當成唯一的撤權訊號;本文件依舊不承諾任何 傳播秒數。
- back-channel 在連線當下判斷解析到的位址。 落在私有網段、loopback、
cloud metadata(
169.254.169.254)、CGNAT(100.64.0.0/10)、IPv6 私有與 link-local、 multicast 與保留/文件用網段就不送。登記時通過的 URI,之後 DNS 指向私有位址一樣會被 拒——登記檢查字面值,送出檢查當下解析到的 IP;而且一個名稱解析出多個位址時,只要有 一個被封鎖就整個不連(不要用 split-horizon 記錄)。通知是至多一次:平台在結束 session 與送出之間重啟,session 仍然是結束的,但不會補送。 - RP-initiated logout 加上瀏覽器綁定。 請求若不是來自持有那顆 session 的瀏覽器,
使用者會先看到確認頁再登出(
id_token_hint可被複製,單靠它不足以把人登出)。 因此從伺服器端呼叫登出端點不會靜默結束 session。post_logout_redirect_uri的驗證 在綁定檢查之前:帶了沒登記的值會直接得到 400 錯誤頁,而且使用者不會被登出 (先前本頁寫成「顯示已登出頁」,那是第一方 hint 才有的行為)。 /oauth2/logout開始接受第一方 ID token 當 hint。 那條路徑的導回條件是「該 client 自己的redirect_uris之一,或該租戶自有網域上的 https URL」——這個放寬只屬於第一方, 第三方 hint 仍然只接受 logout 登記裡的精確值。它不會結束第一方產品的登入(那在各自 BFF 的 cookie 裡)。- 同步 #1425(2026-09-27):第一方 logout 導回只在同一個租戶內查 client,back-channel
黑名單多封一段 IPv6。 兩項都不改第三方看得到的契約形狀,寫在這裡是因為前一條的描述
需要更精確:(1)第一方 hint 那條路徑找 client 的
redirect_uris時,只在該 ID token 自己的租戶內找,不再跨租戶去拿同名 client id 的登記值;(2)back-channel 送信前的位址 黑名單新增::/96,也就是已棄用的 IPv4-compatible IPv6 形式整段不送(例如::a00:1),不看它承載的是哪個 IPv4——IPv4-mapped 形式仍然按它承載的 IPv4 判斷。 對第三方的實務影響只有一個:back-channel 端點的 DNS 不要回 IPv4-compatible 形式的 AAAA 記錄,否則整個名稱都不會被連線。
1.0.0-draft(2026-09-26 修訂)
契約狀態改為 Accepted。 ADR-004 的 D1–D10 已全部實作、審查並合併進平台主線(amygdala 授權與 person extension、third-party gateway、後台整合管理、本文件站),版本號未變。當時端點仍未開放(正式環境的旗標全部關閉)——那是這一天的狀態,端點已於 2026-09-30 開放,見最上方的條目。撤權時限的對外承諾數值仍未定,也不打算對外給數字。
- 新增 403
tenant_not_enabled。 正式環境是逐租戶開通的,這個代碼表示你的租戶尚未在開通名單內。它講的是平台這一側的開通狀態,與呼叫端是誰、要哪一項能力都無關;重試與換 token 都沒有用——簽發端對同一個租戶一樣拒(回 OAuth 的invalid_client)。它不折成 404(即使打在 person 資源上),理由與tenant_suspended相同:講的是你的租戶而不是目標資源存不存在;它也不是可重試的 503,回 503 只會讓還沒開通的租戶一直重試一個永遠不會成功的請求。要開通請由租戶管理員向 LightUp 申請。
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>",恰好擇一;兩個都不帶或都帶是新的 428precondition_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與sharedprofile 是 403profile_not_supported,不是 401。 它們簽章是對的,由授權端拒。- 文件網站網域定案:
developers.lightup.tech(Steven,2026-09-23)。本文件的所有位址至此全部有實際值,不再有佔位符。(當時端點尚未開放;已於 2026-09-30 開放。) - 對外 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 variablehttps://{host}/v1,並帶x-lightup-status: pending-host。候選值是partners.lightup.tech,定案前不得當成可用網址;這個標記還在,文件包就不得對外發布。
1.0.0-draft
狀態:Proposed(草案)。此版本發布時端點尚未上線(端點於 2026-09-30 開放)。
首次發布的對外契約草案。
- 定義
/v1的七個操作:GET /v1/me、GET /v1/tenant、GET /v1/persons/{personId},以及 person extension 的列表、讀取、寫入與刪除。 - 定義兩種授權模式:
client_credentials(profileworkload,主體是 service account)與 authorization code + PKCE(profileself,主體是使用者)。 - 定義 token 驗證契約:ES256、固定 JWKS、
aud = lightup-api、JOSEtyp = at+jwt、TTL 15 分。 - 定義能力目錄(五項,全部
preview)與lightup.<capability>scope 命名空間。 - 定義撤權語意:下一個請求生效,v1 無 allow-cache;不承諾秒數(待實測)。
- 定義錯誤語意:穩定
error代碼、每個回應都有x-request-id、403 與 503 嚴格分開。 - 定義 person extension 的 revision/
If-Match、額度與匯出刪除途徑。
首發當時已知的待定項(歷史紀錄)
下表是首發當時的狀態,保留備查;現況見最上方的 2026-09-30 條目。
| 項目 | 首發當時 | 現況 |
|---|---|---|
| 對外 API host | 已定案 api.lightup.tech;tunnel ingress 尚未建立 |
已上線並接受請求 |
| 文件網站 host | 已定案 developers.lightup.tech |
已上線 |
| 撤權最大傳播時間 | 待實測後公布;只承諾「下一個請求生效」 | 維持不承諾秒數、沒有 SLA |
| Dashboard「整合」頁 | 尚未提供;登記與核准暫由人工流程處理 | 已上線,租戶管理員自助 |
client_credentials grant |
尚未在 token 端點實作,discovery 尚未公告 | 已實作並在 discovery 公告 |
代理(delegated profile) |
不在 v1 範圍;列為 v2 規劃 | 仍不在 v1 範圍 |