LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

機器流程(client_credentials)

背景同步、批次匯入、伺服器對伺服器的整合走這條。主體是 service account,不是某個使用者。

現況:client_credentials 已在 /oauth2/token 上線,discovery 的 grant_types_supported 也已公告它。下面是正式契約,可以直接對正式環境呼叫;mock server 仍可用來離線開發與試錯誤路徑。

你的租戶必須先被開通第三方整合,否則 token 端點回 invalid_client、/v1/* 回 403 tenant_not_enabled。

取 token

POST https://auth.lightup.tech/oauth2/token,application/x-www-form-urlencoded。

欄位 必填 說明
grant_type 必填 固定 client_credentials
client_id 必填 第三方 client id,形狀 tp_<tenant label>_<slug>,由 amygdala 配發。
client_secret 選填 service account 的機器憑證。用 client_secret_basic 時省略。 不要放進版本控制、前端 bundle 或 log。
scope 選填 以空白分隔的能力清單(OAuth 慣例,不是逗號)。 實際拿到的 scope 是各層交集後的結果,可能比請求的少—— 以回應的 scope 欄位為準,不要假設拿到的就是送出去的。

回應

欄位 必填 說明
access_token 必填 profile v2 access token(JWS,header typ: at+jwt、alg: ES256)。 當成不透明字串使用:要知道自己是誰請呼叫 GET /v1/me, 不要在 client 自行解析 claims 做授權判斷。
token_type 必填 固定 Bearer 一律 Bearer。放進 Authorization: Bearer <access_token>。
expires_in 必填 剩餘秒數。v1 是 900(15 分)。不要寫死這個數字—— 照回應的值算到期時間。
scope 必填 實際生效的能力,已是請求 ∩ grant ∩ 方案上限的結果。 可能少於你請求的;以這裡為準。
refresh_token 選填 只有 authorization_code 與 refresh_token 會回。 client_credentials 不回——機器到期直接再換一張。 每次續期都會換新的,舊的立即失效。
{
  "access_token": "<ES256 at+jwt>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "lightup.person.read lightup.person.metadata.write"
}

錯誤

錯誤狀態:400、401、429。 body 是 OAuth 既有的 TokenError 形狀(error + error_description), 不是本 API 其他端點的 Problem——不要把兩者放進同一個解析路徑。

error 意思
invalid_client client id/secret 不對,或 client 已停用
invalid_grant code/refresh token 無效、過期或已用過;PKCE code_verifier 不符
invalid_scope 請求的 scope 不在 client 允許範圍、tenant grant 或方案上限內
unsupported_grant_type 這個 grant 沒開。client_credentials 今天就是這個答案

client_credentials 是安全可重試的(不像 authorization_code 與 refresh_token 是一次性的)。

v1 的三種 grant

grant_type 必填欄位
client_credentials grant_type、client_id
authorization_code grant_type、client_id、code、code_verifier、redirect_uri
refresh_token grant_type、client_id、refresh_token

用 token

GET /v1/me HTTP/1.1
Host: api.lightup.tech
Authorization: Bearer <access_token>

workload token 呼叫 GET /v1/me,回答的是 service account 自己:

{
  "subjectType": "service_account",
  "subjectId": "acc_01j8m4k2r7e9v3xq5w8n0tzc8d",
  "tenantId": "ten_0cqqg39h2199x8fd5kf58s0eb5",
  "clientId": "tp_example_sync",
  "scopes": ["lightup.person.read", "lightup.person.metadata.write"],
  "actor": { "accountId": "acc_01j8m4k2r7e9v3xq5w8n0tzc8d" }
}

機器 token 不會「變成某個使用者」。 機器可以做獲准的組織級同步,但不能聲稱平台已經驗證過某一位終端使用者。如果你的後端用一張機器 token 讀一群人的資料,你的使用者隔離是你的責任,平台不負責。

快取與重取

輪替期間

兩把 secret 並存最長 7 天。輪替時的安全做法:

  1. 平台建立 next secret 並交付給你。
  2. 你先把 next 部署到設定,確認可以換到 token。
  3. 通知平台 promote,current 立刻失效。
  4. 如果第 2 步失敗,舊的還在,可以退回——這就是兩把並存的用意。

不要做的事