起步
LightUp 第三方 API 讓在平台外執行的客戶應用存取有限的平台能力。第一方產品（LightUp 自家 App／Dashboard／Storefront）走各自的 BFF，不走這裡。
契約狀態：Accepted（已定案，實作已合併並上線）。
端點已上線：API host 接受請求，
auth.lightup.tech的第三方登入、token、 introspection 與 logout 端點也都在線上。但第三方整合是逐租戶生效的——租戶的方案不含 第三方整合、或租戶管理員尚未在 Dashboard 打開開關時，每一個呼叫都會被拒成403 tenant_not_enabled，換 token 也一樣。能力目錄裡的每一項都標了
availability：規劃（planned）、預覽（preview）、 正式（ga）。v1 的五項仍全部是預覽：契約已定案、實作已上線，但尚未適用ga的支援與棄用保證，欄位與行為仍可能依實測調整（調整照版本與棄用公告）。 位址已定案並上線（API 是api.lightup.tech，本站是developers.lightup.tech）。
五個步驟
- 找能力：在能力索引找到你要的操作，確認它的
availability、最低方案等級與授權模式。目錄裡沒有的能力就是還沒有；不要從服務名稱推測路徑。 - 登記：依登記與憑證取得 client（
tp_…）與 service account，並由租戶管理員核准這支應用要用的能力集合。 - 取 token：機器流程走 client_credentials；代表使用者的操作走 authorization code + PKCE。
- 第一個受保護讀取：
GET /v1/me。它回答「這張 token 代表誰」，是驗證整條鏈路最便宜的一次呼叫。 - 處理拒絕：照錯誤・限流・重試分辨 401／403／409／429／503。503 不是拒絕，是「現在判不了」，可以重試。
環境與位址
| 項目 | 值 |
|---|---|
| API base URL | https://api.lightup.tech/v1 |
| 文件網站 | https://developers.lightup.tech |
| 授權端點 | https://auth.lightup.tech/oauth2/authorize |
| Token 端點 | https://auth.lightup.tech/oauth2/token |
| JWKS | https://auth.lightup.tech/.well-known/jwks.json |
| API audience | lightup-api |
API host 是 api.lightup.tech（2026-09-23 定案，2026-09-26 上線）。這個網域先前沒有對應的服務，是分配給第三方 Gateway 的，不是從誰手上接管來的。
端點已上線，但第三方整合是逐租戶生效的。 第三方整合是否對某個租戶生效，由兩件事決定：租戶的方案（business 以上才含第三方整合）與租戶管理員自己在 Dashboard「整合」頁打開的開關（平台也可以暫停某個租戶）。 未生效時，/v1/* 每一個呼叫都回 403 tenant_not_enabled，token 端點也會拒（invalid_client），所以重試與換 token 都沒有用。請洽該租戶的管理員（方案不足或尚未開啟）。
這幾個看起來很像的網域不是第三方入口，不要把請求送過去：
| 網域 | 是什麼 |
|---|---|
api.app.lightup.tech |
LightUp 第一方 App 的 BFF |
api.d.lightup.tech |
LightUp 後台的 BFF |
auth.lightup.tech |
登入與 token 端點（是這份契約的一部分，但不是 API host） |
文件網站的網域也已定案：developers.lightup.tech（就是你正在看的這一站）。契約自己標記的待定位址：
目前沒有待定案的位址：契約裡的每一個 server 都已經是正式值。
v1 的範圍
| 操作 | 用途 | 需要的能力 |
|---|---|---|
POST https://auth.lightup.tech/oauth2/token |
取得 access token | |
POST https://auth.lightup.tech/oauth2/revoke |
撤銷自己的 refresh token | |
POST https://auth.lightup.tech/oauth2/introspect |
問一張 token 現在還有不有效 | |
GET /v1/me |
這張 token 代表誰 | lightup.profile.self.read |
GET /v1/tenant |
這張 token 所屬租戶的公開識別欄位 | lightup.tenant.info.read |
GET /v1/persons/{personId} |
獲授權人員的最少欄位 | lightup.person.read |
GET /v1/persons/{personId}/extensions |
列出這個 app 在這個人身上的 extension（有界分頁） | lightup.person.metadata.read |
GET /v1/persons/{personId}/extensions/{extensionId} |
讀一筆 metadata | lightup.person.metadata.read |
PUT /v1/persons/{personId}/extensions/{extensionId} |
建立或整筆取代 metadata | lightup.person.metadata.write |
DELETE /v1/persons/{personId}/extensions/{extensionId} |
刪除一筆 metadata | lightup.person.metadata.write |
v1 的兩種授權模式：
| 模式 | grant | token profile | 主體（sub） |
TTL | refresh |
|---|---|---|---|---|---|
| 機器／背景 | client_credentials |
workload |
service account（acc_…） |
15 分 | 無 |
| 使用者本人 | authorization_code + PKCE |
self |
使用者 person（psn_…） |
15 分 | 有（嚴格 rotation） |
v1 沒有代理（delegation）。 「某人代表另一個人操作」的 delegated profile 屬於 v2 規劃中的範圍，本版文件、範例與 mock server 都不提供，也不要自行實作——外部自行傳 user_id 或 x-user-* 不是委派證明，平台不會接受。