起步
⚠️ API 端點尚未開放
api.lightup.tech目前不接受請求。這份文件描述的是已定案的契約，可以照著開發並對內附的 mock server 驗證，但還沒有可以呼叫的正式環境。預計啟用日期另行公告，會同時更新本頁與變更紀錄。
LightUp 第三方 API 讓在平台外執行的客戶應用存取有限的平台能力。第一方產品（LightUp 自家 App／Dashboard／Storefront）走各自的 BFF，不走這裡。
契約狀態：Proposed（草案）。這份文件描述的端點今天都還不存在。
能力目錄裡的每一項都標了
availability：規劃（planned）、預覽（preview）、 正式（ga）。v1 的五項全部是預覽——契約已定案、可以照著開發並對 mock server 驗證，但實作與開通尚未完成，沒有任何環境保證可以呼叫。 位址已定案（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）。這個網域先前沒有對應的服務，是分配給第三方 Gateway 的，不是從誰手上接管來的。
這幾個看起來很像的網域不是第三方入口，不要把請求送過去：
| 網域 | 是什麼 |
|---|---|
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 | |
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-* 不是委派證明，平台不會接受。
這份文件不代表什麼
- 文件公開不代表 API 免驗證或免授權。每一個呼叫都要有效 token 加上租戶核准的能力。
- 契約寫著某個能力，不代表你的租戶方案含它，也不代表它今天已經可以呼叫。看能力索引的狀態欄。
- 範例使用合成資料。不要把真實憑證、真實客戶資料或內網設定放進範例或 issue。