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

API 參考

本頁完全由版本化的 OpenAPI 文件產生,沒有手寫的端點說明。 契約版本 1.0.0,base URL https://api.lightup.tech/v1。

操作一覽

操作 需要的能力 operationId
POST https://auth.lightup.tech/oauth2/token — issueToken
POST https://auth.lightup.tech/oauth2/revoke — revokeToken
POST https://auth.lightup.tech/oauth2/introspect — introspectToken
GET https://auth.lightup.tech/oauth2/logout — endSession
POST https://auth.lightup.tech/oauth2/logout — endSessionForm
GET /v1/me lightup.profile.self.read getMe
GET /v1/tenant lightup.tenant.info.read getTenant
GET /v1/persons/{personId} lightup.person.read getPerson
GET /v1/persons/{personId}/extensions lightup.person.metadata.read listPersonExtensions
GET /v1/persons/{personId}/extensions/{extensionId} lightup.person.metadata.read getPersonExtension
PUT /v1/persons/{personId}/extensions/{extensionId} lightup.person.metadata.write putPersonExtension
DELETE /v1/persons/{personId}/extensions/{extensionId} lightup.person.metadata.write deletePersonExtension
POST /v1/orders lightup.order.create createOrder
GET /v1/orders/{orderId} lightup.order.read getOrder
POST /v1/orders/{orderId}/cancel lightup.order.cancel cancelOrder
GET /v1/tags/{tagId}/members lightup.tag.read listTagMembers
POST /v1/persons:tags lightup.tag.read listPersonsTags
POST /v1/tags:lookup lightup.tag.read lookupTags
POST /v1/categories:lookup lightup.tag.read lookupTagCategories
POST /v1/persons:resolve lightup.person.resolve resolvePersons
POST /v1/persons:profiles lightup.person.profile.read readPersonProfiles
GET /v1/analytics/traffic/query lightup.analytics.traffic.read queryTrafficAnalytics
GET /v1/analytics/traffic/metrics lightup.analytics.traffic.read listTrafficAnalyticsMetrics
GET /v1/persons/{personId}/wards lightup.person.wards.read listPersonWards
POST /v1/line-targets lightup.line.target listLineTargets
PUT /v1/persons/{personId}/tags/{tagId} lightup.tag.write putPersonTag
DELETE /v1/persons/{personId}/tags/{tagId} lightup.tag.write deletePersonTag
POST /v1/tags/{tagId}/members:add lightup.tag.write addTagMembers
POST /v1/tags/{tagId}/members:remove lightup.tag.write removeTagMembers
POST /v1/tags lightup.tag.define createTag
GET /v1/line-message-groups lightup.line.message_group.read findLineMessageGroups
GET /v1/line-message-groups/{groupId} lightup.line.message_group.read getLineMessageGroup

POST https://auth.lightup.tech/oauth2/token

operationId issueToken 能力 不需要(這裡是取得 token 的地方)

這個端點不在 API host 上。 完整網址就是上面那一個,沒有 /v1 前綴。

換取 access token。不需要 Bearer token(這是取得 token 的地方), client 自己的認證放在表單或 Basic 標頭裡。

v1 支援的 grant

grant_type 用途 得到的 profile client 認證
client_credentials 機器/背景 workload client_secret(confidential)
authorization_code 使用者本人授權完成後換 token self PKCE code_verifier+(confidential 另帶 secret)
refresh_token 續期使用者 token self 同上

三種 grant 都已上線。client_credentials 只在部署開啟第三方整合時才被接受, discovery 的 grant_types_supported 也只在那時公告它(ADR-004 D3);沒開時 /oauth2/token 對它回 unsupported_grant_type。

client 認證方式

client_secret_post(放表單,如下方 schema)或 client_secret_basic (Authorization: Basic base64(client_id:client_secret))。public client 兩者都不用,只靠 PKCE。

不會回什麼

冪等與重試

authorization_code 與 refresh_token 都是一次性的。 重送同一個 code 或已消耗的 refresh_token 會得到 invalid_grant,而且重放 refresh 會殺掉整個 token family(嚴格 rotation,第三方不放寬)。 逾時後不要盲目重試——重新走一次流程。client_credentials 沒有這個問題, 可以安全重試。

限流

這個端點有自己的限流,與 API 的 tenant/account 雙層限流分開。 超過回 429,看 Retry-After。

請求 body

application/x-www-form-urlencoded,schema TokenRequest,必填。

範例 clientCredentials — 機器:client_credentials

{
  "grant_type": "client_credentials",
  "client_id": "tp_asiauni_rehab",
  "client_secret": "<機器憑證,不要寫進版本控制>",
  "scope": "lightup.person.read lightup.person.metadata.write"
}

範例 authorizationCode — 使用者:authorization_code + PKCE

{
  "grant_type": "authorization_code",
  "client_id": "tp_kidpro_parentapp",
  "code": "<授權流程回傳的一次性 code>",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "redirect_uri": "https://app.example.com/callback"
}

範例 refreshToken — 使用者:續期

{
  "grant_type": "refresh_token",
  "client_id": "tp_kidpro_parentapp",
  "refresh_token": "<上一次拿到的 refresh token>"
}

回應

狀態 說明
200 已發出 token
400 RFC 6749 §5.2 的 token 錯誤。注意它用 error 而不是本 API
401 用 client_secret_basic 時 client 認證失敗。
429 token 端點限流。看 Retry-After。

200 範例

範例 workload — client_credentials(無 refresh_token)

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "lightup.person.read lightup.person.metadata.write"
}

範例 self — authorization_code(有 refresh_token)

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "lightup.profile.self.read",
  "refresh_token": "v1.MnR..."
}

400 範例

範例 unsupported

{
  "error": "unsupported_grant_type",
  "error_description": "client_credentials is not enabled on this deployment"
}

範例 invalidScope

{
  "error": "invalid_scope",
  "error_description": "requested scope is not granted to this application"
}

範例 tenantSuspended — 租戶被停權(機器可讀的 error_description)

{
  "error": "invalid_grant",
  "error_description": "tenant_suspended",
  "message": "invalid grant: tenant_suspended"
}

POST https://auth.lightup.tech/oauth2/revoke

operationId revokeToken 能力 不需要(這裡是取得 token 的地方)

這個端點不在 API host 上。 完整網址就是上面那一個,沒有 /v1 前綴。

RFC 7009 token revocation。撤銷你自己這個 client 的 refresh token。

它做什麼、不做什麼

撤掉 這張 refresh token 所屬的整個 token family(同一條 rotation 鏈)
不會撤掉 同一個使用者在其他 client 上的 token
不會結束 使用者在 auth.lightup.tech 上的登入(session 仍在)
不會送出 back-channel logout(這是你自己發起的動作,不是登出事件)
在途 access token 仍有效到自己的 exp(最長 15 分)

要「把使用者登出」而不只是丟掉自己的 refresh token,用 https://auth.lightup.tech/oauth2/logout(RP-Initiated Logout)——那一條會結束 租戶 session,並對這顆 session 上所有第三方 client 送 back-channel logout。

⚠️ /oauth2/logout 綁瀏覽器:請求若不是來自持有那顆 session 的瀏覽器, 使用者會先看到確認頁。所以從伺服器端呼叫它不會靜默結束 session——想在後端 丟掉自己存的憑證,用的就是這裡的 revoke。它的 post_logout_redirect_uri 也只 接受 logout 登記裡的精確值,不符是 400 錯誤頁且使用者不會被登出。

租戶怎麼決定

以 client 登記的租戶為準。 tp_ client 的租戶由它自己的登記記錄決定,與 token 端點是同一條解析;不由 redirect_uri 的網域決定,也不由請求裡的任何 參數決定——你不需要(也不能)指定租戶。

client 認證

client_secret_basic 或 client_secret_post,擇一;兩者同時出現是 400。 public client 只帶 client_id。

回應

依 RFC 7009,成功一律 200 且無 body。token 不存在、已過期、或屬於別的 client,同樣是 200 且不做事——不會告訴你那張 token 存不存在。所以這個端點 天然冪等,逾時可以安全重試。

請求 body

application/x-www-form-urlencoded,schema object,必填。

範例 revoke — 撤銷自己的 refresh token

{
  "token": "<上一次拿到的 refresh token>",
  "token_type_hint": "refresh_token",
  "client_id": "tp_kidpro_parentapp",
  "client_secret": "<client 憑證,不要寫進版本控制>"
}

回應

狀態 說明
200 已撤銷,或那張 token 本來就不在(RFC 7009 不區分)。無 body。
400 請求形狀不對,或同時用了兩種 client 認證方式。
401 client 認證失敗(invalid_client)。

POST https://auth.lightup.tech/oauth2/introspect

operationId introspectToken 能力 不需要(這裡是取得 token 的地方)

這個端點不在 API host 上。 完整網址就是上面那一個,沒有 /v1 前綴。

RFC 7662 token introspection。這是判斷「使用者的登入現在還算不算有效」的權威 來源——back-channel logout 是 best effort,不可當成唯一的撤權訊號:通知是 至多一次(平台在結束 session 與送出之間重啟就不會補送),而且送信的連線 當下會判斷解析到的位址,落在私有位址就不送(登記時通過的 URI 也一樣, 因為登記檢查字面值、送出檢查當下解析到的 IP;一個名稱解析出多個位址時,只要有 一個被封鎖就整個不連)。

誰可以呼叫

條件 不符時
已啟用(enabled)的第三方 client 401 invalid_client
confidential client(有 client secret) 401 invalid_client。public client 沒有可認證的東西,一律不准
client_secret_basic 或 client_secret_post,擇一 兩者同時出現是 401 invalid_client

可以查什麼

只能查自己的 token。 你自己這個 client 的 access token 或 refresh token 才會 回 active: true;別人的 token、ID token、格式不對的字串,一律 {"active": false}——不會告訴你它屬於誰、也不會告訴你它存不存在。

非 active 不分原因

{"active": false} 涵蓋全部:不存在、已過期、已消耗、已撤銷、屬於別人、 背後的租戶 session 已結束。刻意不細分,細分等於幫呼叫端做探測。

fail-closed

讀不到或判不完(Couchbase/授權端錯誤、逾時)→ 503 temporarily_unavailable, 絕不回 active: true。呼叫端也要 fail-closed:判不了就當作不可用。

沒有快取

每次都是即時讀取。撤權寫入成功後,下一次 introspect 就是 active: false。

限流

與登入共用 per-IP 限流,超過回 429 slow_down。

一個實用場景:refresh 結果未知

refresh 呼叫逾時而不知道有沒有成功時,不可重送同一張 refresh token(重送 = reuse = 竊用訊號,會撤掉整個 family 並且結束整顆登入)。改成拿舊的那張來 introspect:active: true 表示那次 refresh 沒生效、可以安全重送; active: false 表示已消耗或已撤,請使用者重新登入。

請求 body

application/x-www-form-urlencoded,schema object,必填。

範例 introspect — 查自己發出去的 access token

{
  "token": "<要檢查的 token>",
  "token_type_hint": "access_token",
  "client_id": "tp_kidpro_parentapp",
  "client_secret": "<client 憑證,不要寫進版本控制>"
}

回應

狀態 說明
200 已判定。active: true 帶完整欄位;active: false 只有這一個欄位。
400 請求 body 解不開(不是合法的 form 編碼)。error 是 invalid_request。
401 client 認證失敗,或這個 client 不准 introspect(不是第三方、
404 第三方功能在本部署尚未開啟,這條路由不存在。error 是 not_found。
429 限流(與登入共用 per-IP 額度),error 是 slow_down。
503 現在判不了(讀取失敗或逾時)。這不是 active: false,

200 範例

範例 active — 有效的 access token

{
  "active": true,
  "sub": "psn_01j8m4k2r7e9v3xq5w8n0tzh6p",
  "sid": "8f14e45fea5c4f7a9a1b2c3d4e5f6a7b",
  "client_id": "tp_kidpro_parentapp",
  "token_type": "Bearer",
  "exp": 1790000900,
  "iat": 1790000000,
  "auth_time": 1789999500,
  "acr": "urn:lightup:loa:1",
  "tenant_id": "ten_01j8m4k2r7e9v3xq5w8n0tzh6p",
  "scope": "lightup.profile.self.read"
}

範例 activeRefresh — 有效的 refresh token

{
  "active": true,
  "sub": "psn_01j8m4k2r7e9v3xq5w8n0tzh6p",
  "sid": "8f14e45fea5c4f7a9a1b2c3d4e5f6a7b",
  "client_id": "tp_kidpro_parentapp",
  "token_type": "refresh_token",
  "exp": 1790086400,
  "iat": 1790000000,
  "auth_time": 1789999500,
  "acr": "urn:lightup:loa:2",
  "tenant_id": "ten_01j8m4k2r7e9v3xq5w8n0tzh6p",
  "scope": "lightup.profile.self.read"
}

範例 inactive — 無效(不分原因)

{
  "active": false
}

GET https://auth.lightup.tech/oauth2/logout

operationId endSession 能力 不需要(這裡是取得 token 的地方)

這個端點不在 API host 上。 完整網址就是上面那一個,沒有 /v1 前綴。

OpenID Connect RP-Initiated Logout 1.0。把使用者的瀏覽器導到這裡(不是從伺服器 端呼叫):結束使用者在平台上的那次登入,並對同一次登入上所有第三方 client 送 back-channel logout(包含發起的你自己)。

這是瀏覽器端點:回應一律是 HTML 頁面或 302 轉址,不是 JSON。參數放在 query string;同一組參數也可以用 POST 表單送(見下一個操作)。

它做什麼、不做什麼

結束 使用者在 auth.lightup.tech 上的那次登入(id_token_hint 的 sid 指向的 session)
送出 back-channel logout 給這次登入上所有登記了 back-channel URI 的第三方 client
之後 綁在這次登入上的 token,introspect 一律回 active: false,refresh 也換不到新 token
在途 access token 仍有效到自己的 exp(最長 15 分)

只想丟掉自己這個 app 存的 refresh token、不把使用者登出,用 /oauth2/revoke。

id_token_hint 必填

沒有 hint 的請求一律 400——否則任何網頁都能把人登出。hint 必須是平台簽發的 ID token(ES256、簽章金鑰在平台 JWKS 上);已過期的也接受(規格允許)。 帶了 client_id 時必須等於 hint 的 aud,不符是 400。

post_logout_redirect_uri

瀏覽器綁定:不是同一個瀏覽器會先看到確認頁

發出請求的瀏覽器若持有 hint 指向的那次登入(它的 session cookie 推得出同一個 sid),直接登出。否則先回一張確認頁:一張 POST 回 /oauth2/logout 的表單, 把 id_token_hint/client_id/post_logout_redirect_uri/state 原樣帶著, 外加一次性的 confirm 欄位與對應的 __Host-oidc_logout_confirm cookie (300 秒);使用者按下確認才真的登出。所以從伺服器端呼叫這條路由不會靜默結束 session,只會拿到確認頁。

順序:post_logout_redirect_uri 的驗證在綁定檢查之前——帶了未登記的 redirect 會直接拿到 400 錯誤頁,不會先看到確認頁。

冪等

對已經結束的登入再登出一次不是錯誤:結果仍是「已登出」頁或 302(瀏覽器不持有 那次登入時,一樣先經過確認頁)。back-channel logout 不會再送第二次。

第一方 hint

hint 若是 LightUp 第一方產品的 ID token,這條路由也接受,但不結束任何 session, 也沒有確認頁;post_logout_redirect_uri 不符時顯示「已登出」頁而不是 400。這個放寬 不適用於第三方 hint。

每個回應都帶

Cache-Control: no-store、Referrer-Policy: no-referrer,以及 Content-Security-Policy: default-src 'none'; form-action 'self'; frame-ancestors 'none' (頁面不能被嵌進 iframe)。

參數

名稱 位置 必填 型別 說明
id_token_hint query 是 string 平台簽發給這個 client 的 ID token。已過期的也接受。
client_id query 否 string 可省略;帶了就必須等於 hint 的 aud。
post_logout_redirect_uri query 否 string 可省略;帶了就必須精確等於 logout 登記裡的值之一。 format uri
state query 否 string 可省略;導回時以 state query 參數附加回去。

回應

狀態 說明
200 「已登出」頁,或確認頁(登入還沒結束,等使用者按下確認)。
302 已登出,導回已登記的 post_logout_redirect_uri。
400 錯誤頁(「無法處理這次登出請求」),使用者沒有被登出。
404 第三方功能在本部署尚未開啟,這條路由不存在(錯誤頁)。
503 錯誤頁:平台現在處理不了這次登出,請稍後重試。

POST https://auth.lightup.tech/oauth2/logout

operationId endSessionForm 能力 不需要(這裡是取得 token 的地方)

這個端點不在 API host 上。 完整網址就是上面那一個,沒有 /v1 前綴。

與 GET /oauth2/logout 同一個端點、同一套規則,參數改放 application/x-www-form-urlencoded 表單。平台自己的確認頁就是用這個形式送回來的 (多帶一個 confirm 欄位);你的應用也可以用自動送出的表單把使用者帶過來。

body 不是合法的表單編碼時回 400 錯誤頁。其餘行為見 GET /oauth2/logout。

請求 body

application/x-www-form-urlencoded,schema object,必填。

範例 logout — 登出並導回已登記的頁面

{
  "id_token_hint": "<登入時拿到的 ID token>",
  "client_id": "tp_kidpro_parentapp",
  "post_logout_redirect_uri": "https://app.example.com/signed-out",
  "state": "af0ifjsldkj"
}

回應

狀態 說明
200 「已登出」頁,或確認頁(登入還沒結束,等使用者按下確認)。
302 已登出,導回已登記的 post_logout_redirect_uri。
400 錯誤頁(「無法處理這次登出請求」),使用者沒有被登出。
404 第三方功能在本部署尚未開啟,這條路由不存在(錯誤頁)。
503 錯誤頁:平台現在處理不了這次登出,請稍後重試。

GET /v1/me

operationId getMe 能力 lightup.profile.self.read

能力:lightup.profile.self.read(方案 L1 起)

回傳這張 token 自己的身分,不是任意人的資料。v1 有兩種 profile:

token profile subjectType subjectId actor
self person 本人 psn_… 本人 acc_…
workload service_account acc_…(kind=service) 同 subjectId

機器 token 呼叫這支不會「變成某個使用者」:workload 的答案就是 service account 自己。機器能讀一群人的資料,不代表平台驗證過任何一位終端使用者 (計畫 §4.1)。

冪等:GET,天然冪等。不計入寫入額度。

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 self — 使用者本人的 token

{
  "subjectType": "person",
  "subjectId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
  "tenantId": "ten_0cqqg39h2199x8fd5kf58s0eb5",
  "clientId": "tp_kidpro_parentapp",
  "scopes": [
    "lightup.profile.self.read",
    "lightup.person.metadata.read"
  ],
  "actor": {
    "accountId": "acc_01j8m4k2r7e9v3xq5w8n0tzb7c"
  }
}

範例 workload — 機器 token

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

GET /v1/tenant

operationId getTenant 能力 lightup.tenant.info.read

能力:lightup.tenant.info.read(方案 L1 起)

租戶由 token 決定,不由參數決定。沒有 GET /v1/tenants/{id}: 一張 token 只能看自己的租戶(計畫 §9 驗收矩陣第 1 列)。

回傳的是識別欄位,不是租戶設定。不含方案細節、聯絡人、網域設定、 社群 provider、LDAP 或任何秘密。

沒有 state 欄位(v1 刻意不給)

這支不回租戶的營運狀態。停權租戶不需要用一個欄位來表達: 它的 token 在簽發與每次判權兩處都已經被擋下,所以呼叫端 根本拿不到能成功呼叫的 token——狀態會以 401/403 的形式出現, 而不是以一個要自己判讀的欄位出現。

少一個欄位也少一種錯誤用法:如果 Gateway 在上游沒給值時填一個預設的 active,partner 會據此決定要不要送出寫入——那正是這種欄位最容易 造成的傷害。v1 的選擇是不給,而不是猜。

冪等:GET。

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "tenantId": "ten_0cqqg39h2199x8fd5kf58s0eb5",
  "displayName": "KidPro"
}

GET /v1/persons/{personId}

operationId getPerson 能力 lightup.person.read

能力:lightup.person.read(方案 L2 起)

只回三個欄位:personId、displayName、createdAt。 沒有 email、沒有手機、沒有生日、沒有關係、沒有訂單、沒有任何 channel identity。 要更多欄位是新的能力,要新的 grant,不是在這裡加參數。

這支不回 metadata(計畫 §6:「一般主檔 GET 不順便吐出全部 metadata」)。 metadata 走 /v1/persons/{personId}/extensions/...,且需要另外的能力。

授權:除了 capability 之外,Amygdala 還會確認這個租戶對這個人有有效關係。 關係不成立時回 404,不是 403 —— caller 不應該從錯誤碼推斷這個 person 是否存在 (ADR-004 D9)。

冪等:GET。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
  "displayName": "王小明",
  "createdAt": "2025-03-11T02:14:07Z"
}

GET /v1/persons/{personId}/extensions

operationId listPersonExtensions 能力 lightup.person.metadata.read

能力:lightup.person.metadata.read(方案 L2 起)

只列出呼叫端自己擁有的 extension。 同租戶的別的 app 寫的 extension 不會出現在這裡,也不會被計入 total(計畫 §9 驗收矩陣第 2 列)。

分頁是有界的:limit 預設 20、上限 100。用 cursor 取下一頁。 沒有「全部拉下來」的參數,也沒有任意 JSON 查詢(計畫 §6:v1 只有 key lookup + 有界分頁)。

冪等:GET。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
limit query 否 integer 每頁筆數。預設 20,上限 100。超過上限 → 422。 預設 20;最小 1;最大 100
cursor query 否 string 上一頁回應的 nextCursor。不透明字串,不要解析;換版本後形狀可能改變。 最長 512

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "items": [
    {
      "extensionId": "rehab_progress",
      "schemaVersion": 3,
      "etag": "\"17\"",
      "updatedAt": "2026-09-20T08:31:55Z",
      "updatedBy": "tp_asiauni_rehab"
    }
  ],
  "nextCursor": null
}

GET /v1/persons/{personId}/extensions/{extensionId}

operationId getPersonExtension 能力 lightup.person.metadata.read

能力:lightup.person.metadata.read(方案 L2 起)

回應帶 ETag。要改這筆資料,把 ETag 原封不動放進 If-Match。

404 的三種情況回答一樣:extension 未登記、這個 app 不是它的 owner、 資料不存在。錯誤碼不透露資源是否存在(ADR-004 D9)。

冪等:GET。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
extensionId path 是 ExtensionId 登記時由平台配發的 extension id。不可用會改名的功能名稱當身分(計畫 §6)。 未登記或不屬於呼叫端 → 404。 pattern ^[a-z][a-z0-9_]{2,63}$

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "extensionId": "rehab_progress",
  "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
  "schemaVersion": 3,
  "etag": "\"17\"",
  "data": {
    "lastSessionAt": "2026-09-19T09:00:00Z",
    "completedUnits": 12
  },
  "createdAt": "2026-04-02T01:00:00Z",
  "updatedAt": "2026-09-20T08:31:55Z",
  "updatedBy": "tp_asiauni_rehab"
}

PUT /v1/persons/{personId}/extensions/{extensionId}

operationId putPersonExtension 能力 lightup.person.metadata.write

能力:lightup.person.metadata.write(方案 L2 起)

整筆取代,不是 patch:data 就是新的完整內容。

並行控制(必讀)

每個 PUT 必須恰好帶一個前置條件標頭,而且是 RFC 9110 的標準語意, 沒有自訂延伸:

If-Match 不接受 *(那是 DELETE 才有的用法)。兩個都不帶、或兩個 都帶,一律 428 precondition_required——本 API 沒有「無條件覆寫」這個操作, 因為那正是遺失更新的來源。

情境 送什麼 結果
建立新的一筆 If-None-Match: * 201
建立但它已經存在 If-None-Match: * 409 already_exists
更新既有一筆 If-Match: "<etag>" 200
更新但版本已被別人改掉 If-Match: "<舊 etag>" 409 revision_conflict
更新但那筆已被刪除 If-Match: "<etag>" 404
兩個都沒帶,或兩個都帶 — 428 precondition_required

兩個 client 同時寫,後到的那個會拿到 409,不會覆蓋前一個(計畫 §6)。 正確處理方式:重新 GET、合併、帶新的 ETag 重送。

ℹ️ 為什麼建立衝突是 409 而不是 412。 RFC 9110 對失敗的前置條件給的是 412;本 API 刻意把它收斂成 409,讓「你和別人撞上了」只有一個狀態碼, client 的錯誤處理只要分辨 Problem.error(already_exists vs revision_conflict)就夠,不必同時處理 409 與 412 兩條路徑。 428 則保留給「你根本沒表明意圖」,那是 client 的 bug,不是衝突。

額度(計畫 §6/§7)

限制 值 超過時
單筆 data 大小 16 KiB 413
每 tenant 每 extension 筆數 50,000 422 quota_exceeded
每 tenant extension 數 20 422 quota_exceeded

額度判定與寫入在同一交易內完成,所以大量並行寫入不會衝破上限 (計畫 §7「交易內處理並行寫入的額度競爭」)。 額度滿不會刪任何既有資料;讀取與刪除照常可用。

這裡不能放什麼

照片、逐題事件、無界成長的列表,以及任何被當成 permission、餘額、購買權益 或身份綁定的欄位(計畫 §6)。平台不會因為 metadata 說了什麼而授予任何權限。

冪等

同樣的 data + 同樣的 If-Match 重送:第一次成功後 ETag 就變了, 第二次會得到 409。要安全重試,重讀後再送。 計量以 x-request-id 為 idempotency key,重試不重複計量。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
extensionId path 是 ExtensionId 登記時由平台配發的 extension id。不可用會改名的功能名稱當身分(計畫 §6)。 未登記或不屬於呼叫端 → 404。 pattern ^[a-z][a-z0-9_]{2,63}$
If-Match header 否 string 更新既有資料時使用,值是上次讀到的 ETag(RFC 9110 §13.1.1)。 required: false 是因為 OpenAPI 無法表達「If-Match 與 If-None-Match 恰好擇一」。這不代表可以兩個都不帶——兩個都不帶或兩個都帶都是 428 precondition_required。建立新資料請改用 If-None-Match: *。 不接受 *(schema 就擋掉)。If-Match: * 在 RFC 裡的意思是 「只要它存在」,那是 DELETE 的用法,拿來建立資料會是錯的。 pattern ^"[^"]+"$
If-None-Match header 否 string 建立新資料時使用,唯一合法值是 *,意思是「只有在它還不存在時才寫」 (RFC 9110 §13.1.2)。 它已經存在 → 409 already_exists(不是 412,見 PUT 的說明)。 required: false 的理由同 If-Match:兩者恰好擇一,OpenAPI 表達不了, 所以由伺服器以 428 執行。 pattern ^\*$

請求 body

application/json,schema PersonExtensionWrite,必填。

範例 default

{
  "schemaVersion": 3,
  "data": {
    "lastSessionAt": "2026-09-22T09:00:00Z",
    "completedUnits": 13
  }
}

回應

狀態 說明
200 已更新
201 已建立
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 你和別人撞上了。沒有任何東西被寫入。 兩種:
413 單筆 data 超過 16 KiB。縮小內容,或把大東西放在你自己的資料庫
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
428 這個寫入沒有表明它的前置條件(RFC 6585 §3)。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

DELETE /v1/persons/{personId}/extensions/{extensionId}

operationId deletePersonExtension 能力 lightup.person.metadata.write

能力:lightup.person.metadata.write(方案 L2 起)

冪等:已經不存在也回 204(計畫 §6「刪除可冪等」)。

If-Match 必填(required: true,schema 驗得到):

「已經不存在」與「存在但版本不符」不同:前者 204(冪等),後者 409。 DELETE 不看 If-None-Match;送了會被忽略。

刪除釋放筆數額度,但不會回填任何歷史;要保留請先匯出。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
extensionId path 是 ExtensionId 登記時由平台配發的 extension id。不可用會改名的功能名稱當身分(計畫 §6)。 未登記或不屬於呼叫端 → 404。 pattern ^[a-z][a-z0-9_]{2,63}$
If-Match header 是 string 必填(required: true,schema 驗得到;DELETE 只有這一個前置條件標頭, 不存在擇一的問題)。 - "<etag>" — 只刪那一版;版本不符 → 409 revision_conflict - * — 不論版本都刪(RFC 9110 §13.1.1 的標準語意:「只要它存在」) 省略 → 428 precondition_required。已經不存在 → 204(冪等)。 pattern `^(*

回應

狀態 說明
204 已刪除,或原本就不存在(冪等)
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 你和別人撞上了。沒有任何東西被寫入。 兩種:
428 這個寫入沒有表明它的前置條件(RFC 6585 §3)。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/orders

operationId createOrder 能力 lightup.order.create

能力:lightup.order.create(方案 L2 起)·可用狀態:預覽(preview)

為租戶的一位客戶建立未付款訂單。價格一律取自商品目錄:請求沒有單價欄位, 帶了未知欄位會被 422 schema_invalid 拒絕。

只限機器流程:必須是 workload token(service account)。使用者本人的 self token 會得到 403 profile_not_supported。

冪等(必讀)

Idempotency-Key 必填,1–200 個可見 ASCII 字元(0x21–0x7E),不可有空白。 缺漏或格式不對 → 422 schema_invalid,而且在判權之前就回。

情境 結果
第一次送出這個 key 201,建立新訂單
同一個 key、同一份請求,24 小時內重送 200,回傳原來那張訂單,不會建立第二張
同一個 key、不同的請求內容 409 idempotency_key_reused
同一個 key 的上一次請求還在處理中 409 request_in_progress,帶 Retry-After: 2

網路逾時而不知道有沒有建立成功:用同一個 key、同一份請求重送即可,不會重複建單。

付款期限

expiresAt 選填(RFC 3339)。有給的話必須晚於現在、且不超過現在起 10 年,否則 422 schema_invalid。沒給的話,訂單會在 30 分鐘後自動取消。

買家與操作者

參數

名稱 位置 必填 型別 說明
Idempotency-Key header 是 string 建立訂單的冪等鍵:1–200 個可見 ASCII 字元(0x21–0x7E),不可有空白。 同一個 key 重送同一份請求,回原來那張訂單(200);同一個 key 用在不同的請求 上,回 409 idempotency_key_reused。缺漏或格式不對 → 422 schema_invalid,在判權之前。 pattern ^[!-~]{1,200}$;最長 200
X-LightUp-Operator header 否 string 選填。聲明「是哪位員工操作」,例如 usr_…; name=%E7%8E%8B。只是註記:Gateway 原樣交給 amygdala 簽進下游 token 供稽核;不參與授權,也不被轉送。 必須是非空白、≤ 256 位元組、不含控制字元的字串;否則 422 schema_invalid。 最長 256

請求 body

application/json,schema OrderCreateRequest,必填。

範例 makeup — 兩個品項、附屬性、設定付款期限

{
  "customerPersonId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
  "items": [
    {
      "productId": "ae886b43-83d5-4ce7-8a0f-7ffc7daa39da",
      "quantity": 1,
      "attributes": {
        "leaveId": "lv_example_0001",
        "leaveSku": "example-leave-sku",
        "makeupSku": "example-makeup-sku"
      }
    },
    {
      "productId": "3f0c2a6e-9b1d-4e51-8c7a-2d5f8e1b9a04",
      "quantity": 2
    }
  ],
  "remark": "補課費",
  "expiresAt": "2026-10-20T18:00:00+08:00"
}

回應

狀態 說明
200 同一個 Idempotency-Key、同一份請求的重送,回傳原來那張訂單
201 已建立新訂單
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
409 訂單操作與現況衝突。沒有任何東西被寫入或改變。 三種:
422 請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種:
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

GET /v1/orders/{orderId}

operationId getOrder 能力 lightup.order.read

能力:lightup.order.read(方案 L2 起)·可用狀態:預覽(preview)

回傳這支應用程式自己建立的訂單。別的 client 建立的、別的租戶的、或根本不存在的 訂單,一律回 404 not_found,不分辨(ADR-004 D9)。

orderId 形狀不合(不是 1–128 個 [A-Za-z0-9_-])也回 404,而且在判權之前就回。

回應只有 Order 定義的欄位;訂單上其他內部欄位不會出現。金額是 JSON 數字。

冪等:GET,天然冪等。

參數

名稱 位置 必填 型別 說明
orderId path 是 string 訂單 id,就是建立時回傳的 orderId。1–128 個 [A-Za-z0-9_-];形狀不合 → 404。 pattern ^[A-Za-z0-9_-]+$;最長 128

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/orders/{orderId}/cancel

operationId cancelOrder 能力 lightup.order.cancel

能力:lightup.order.cancel(方案 L2 起)·可用狀態:預覽(preview)

只能取消未付款且仍可取消的訂單,成功回 200 與取消後的 Order。

不可取消(已取消、已付款、或已進入不可取消的狀態)→ 409 order_not_cancellable。 detail 是下游訂單服務的代碼與訊息,格式 "{code}: {message}",例如 ORDER_ALREADY_CANCELLED: …、ORDER_NOT_CANCELLABLE: …、ORDER_CANCEL_PENDING_OPERATOR: …。 409 時沒有任何東西被改變。

別的 client 建立的、別的租戶的、或不存在的訂單 → 404 not_found。

冪等:重送已取消的訂單會得到 409 order_not_cancellable(ORDER_ALREADY_CANCELLED), 不是 200。要確認現況,讀 GET /v1/orders/{orderId} 的 status。

參數

名稱 位置 必填 型別 說明
orderId path 是 string 訂單 id,就是建立時回傳的 orderId。1–128 個 [A-Za-z0-9_-];形狀不合 → 404。 pattern ^[A-Za-z0-9_-]+$;最長 128

請求 body

application/json,schema OrderCancelRequest,必填。

範例 default

{
  "reason": "客戶來電取消"
}

回應

狀態 說明
200 已取消,回傳取消後的訂單
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 訂單操作與現況衝突。沒有任何東西被寫入或改變。 三種:
422 請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種:
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

GET /v1/tags/{tagId}/members

operationId listTagMembers 能力 lightup.tag.read

能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)

回傳帶著這個標籤的客戶,一次一頁,依 person id 排序。回應有 next 時,把它原樣放進下一次的 after 取下一頁;沒有 next 就是最後一頁。

只限機器流程:必須是 workload token(service account)。使用者本人的 self token 會得到 403 profile_not_supported。

冪等:GET,天然冪等。

參數

名稱 位置 必填 型別 說明
tagId path 是 TagId 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64
after query 否 PersonTypeId 上一頁回應的 next(一個 psn_ TypeID)。省略就從第一頁開始。不是 psn_ TypeID → 422 schema_invalid。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
limit query 否 integer 每頁筆數,1–100。省略時是 50。超出範圍 → 422 schema_invalid。 預設 50;最小 1;最大 100

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "members": [
    {
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
      "addedAt": "2026-10-19T09:30:00Z"
    }
  ],
  "next": "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
}

POST /v1/persons:tags

operationId listPersonsTags 能力 lightup.tag.read

能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)

一次最多 100 位客戶,回傳每一位帶著的標籤與加上的時間。

只限機器流程(workload token);使用者本人的 token 會得到 403 profile_not_supported。

personIds 是 1–100 個 psn_ TypeID。只要有一個不合格,整個請求就是 422 schema_invalid(在判權之前):清單建錯了就不是「一半對」。

冪等:唯讀,可以安全重送。

請求 body

application/json,schema PersonIdsRequest,必填。

範例 default

{
  "personIds": [
    "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
  ]
}

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/tags:lookup

operationId lookupTags 能力 lightup.tag.read

能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)

一次最多 100 個名稱(每個 1–200 字元),每個名稱回一個結果:

outcome 意思
FOUND 剛好一個標籤叫這個名稱,tagId 就是它
NOT_FOUND 沒有標籤叫這個名稱
AMBIGUOUS 不只一個標籤叫這個名稱(通常在不同分類下)。帶 categoryNodeId 限定分類再查一次

categoryNodeId 選填,只在那一個分類下找;它來自 POST /v1/categories:lookup。

只限機器流程(workload token)。

冪等:唯讀,可以安全重送。

請求 body

application/json,schema TagLookupRequest,必填。

範例 default

{
  "names": [
    "永和 週六"
  ],
  "categoryNodeId": "node-7"
}

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/categories:lookup

operationId lookupTagCategories 能力 lightup.tag.read

能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)

一次最多 100 個名稱(每個 1–200 字元),每個名稱回一個結果,outcome 與 POST /v1/tags:lookup 相同(FOUND/NOT_FOUND/AMBIGUOUS)。FOUND 時帶 categoryNodeId;AMBIGUOUS 時帶 candidates(每一個叫這個名稱的分類 id)。

categoryNodeId 就是 POST /v1/tags:lookup 與 POST /v1/tags 要的那個值。

只限機器流程(workload token)。

冪等:唯讀,可以安全重送。

請求 body

application/json,schema CategoryLookupRequest,必填。

範例 default

{
  "names": [
    "上課時段"
  ]
}

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/persons:resolve

operationId resolvePersons 能力 lightup.person.resolve

能力:lightup.person.resolve(方案 L2 起)·可用狀態:預覽(preview)

一次最多 500 個舊客戶 id(每個 1–128 字元),每個回一個結果:

outcome 意思
RESOLVED 對應到一位客戶,personId 就是他
NOT_FOUND 這個租戶沒有這個舊 id 的對應
AMBIGUOUS 平台存的對應彼此不一致(例如對到兩位客戶)。不要替它選邊,也不要對它發送行銷訊息
INVALID 這個值不是任何一種拼法的使用者 id 或 person id

只限機器流程(workload token)。

冪等:唯讀,可以安全重送。

請求 body

application/json,schema PersonResolveRequest,必填。

範例 default

{
  "legacyIds": [
    "5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33"
  ]
}

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/persons:profiles

operationId readPersonProfiles 能力 lightup.person.profile.read

能力:lightup.person.profile.read(方案 L2 起)·可用狀態:預覽(preview)

一次最多 500 個 id(每個 1–128 字元),每個回一個結果。每個 id 可以是裸的舊客戶 UUID, 也可以是 psn_ person id,平台分辨的方式與 POST /v1/persons:resolve 完全相同。 沒有列出全部客戶的形式:要讀誰,就要逐一指名。

outcome 意思
FOUND 找到一位客戶,帶 personId 與五個基本資料欄位
NOT_FOUND 這個租戶沒有這個 id 的客戶
AMBIGUOUS 平台存的對應彼此不一致(例如對到兩位客戶)。不要替它選邊
INVALID 這個值不是任何一種拼法的使用者 id 或 person id

只有 FOUND 帶資料:personId 與 givenName、familyName、displayName、birthDate、 gender 五個欄位。這五個欄位一定出現,沒有值時是 null。其他結果只有 id 與 outcome。

只限機器流程(workload token)。授權服務每次呼叫記一筆稽核紀錄。

冪等:唯讀,可以安全重送。

請求 body

application/json,schema PersonProfilesRequest,必填。

範例 default

{
  "ids": [
    "5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33",
    "psn_01j8m4k2r7e9v3xq5w8n0tza6c"
  ]
}

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "profiles": [
    {
      "id": "5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33",
      "outcome": "FOUND",
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
      "givenName": "小明",
      "familyName": "王",
      "displayName": "王小明",
      "birthDate": "2019-04-07",
      "gender": "male"
    },
    {
      "id": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
      "outcome": "FOUND",
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
      "givenName": null,
      "familyName": null,
      "displayName": "新孩子",
      "birthDate": null,
      "gender": null
    }
  ]
}

GET /v1/analytics/traffic/query

operationId queryTrafficAnalytics 能力 lightup.analytics.traffic.read

能力:lightup.analytics.traffic.read(方案 L2 起)·可用狀態:預覽(preview)

讀取一個指標。回傳的都是彙總:次數與比例,不含金額,也不含任何個人資料,網址路徑中的識別碼會換成 :id。依渠道的訂單與營收不在這一項。

只限機器流程(workload token)。

冪等:唯讀,可以安全重送。

參數

名稱 位置 必填 型別 說明
topic query 是 string 指標所屬的主題:traffic 或 checkout。可用的組合見 GET /v1/analytics/traffic/metrics。 最長 64
metric query 是 string 指標名稱,例如 channels。 最長 64
granularity query 否 string 時間粒度,例如 day。指標支援哪些粒度,見 GET /v1/analytics/traffic/metrics。 最長 64
start query 否 string 範圍起點(含),租戶時區的日期,YYYY-MM-DD。要和 end 一起給;和 quickRange 二選一。 最長 64
end query 否 string 範圍終點(不含),租戶時區的日期,YYYY-MM-DD。 最長 64
quickRange query 否 string 常用範圍,和 start/end 二選一。 列舉:this_month_to_date、last_month、same_month_last_year、this_quarter_to_date、last_quarter、this_year_to_date、last_year、last_12_months
compare query 否 string 比較期,預設 none。 列舉:none、previous_period、previous_year
dimension query 否 string 只有少數指標用得到,可用的值見 GET /v1/analytics/traffic/metrics。 最長 64
topN query 否 string 只對有排名的指標有效。 最長 64

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "meta": {
    "topic": "traffic",
    "metric": "channels",
    "granularity": "day",
    "timezone": "Asia/Taipei",
    "currency": "TWD",
    "rangeStart": "2026-11-05",
    "rangeEnd": "2026-11-06",
    "isPartial": false,
    "generatedAt": "2026-11-06T01:00:00Z",
    "notes": []
  },
  "schema": [
    {
      "name": "period",
      "type": "string",
      "semantic": "time",
      "unit": ""
    },
    {
      "name": "channel",
      "type": "string",
      "semantic": "dimension",
      "unit": ""
    },
    {
      "name": "sessions",
      "type": "number",
      "semantic": "measure",
      "unit": "sessions"
    }
  ],
  "rows": [
    {
      "dimensions": {
        "period": "2026-11-05",
        "channel": "meta"
      },
      "measures": {
        "sessions": 128
      }
    }
  ],
  "series": []
}

GET /v1/analytics/traffic/metrics

operationId listTrafficAnalyticsMetrics 能力 lightup.analytics.traffic.read

能力:lightup.analytics.traffic.read(方案 L2 起)·可用狀態:預覽(preview)

列出這個領域開放的指標,以及每個指標支援的粒度、分組與量值。不接受任何參數。

只限機器流程(workload token)。

冪等:唯讀,可以安全重送。

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "metrics": [
    {
      "topic": "traffic",
      "metric": "channels",
      "granularities": [
        "day",
        "week",
        "month"
      ],
      "groupBy": [
        "period",
        "channel"
      ],
      "measures": [
        "sessions"
      ]
    }
  ]
}

GET /v1/persons/{personId}/wards

operationId listPersonWards 能力 lightup.person.wards.read

能力:lightup.person.wards.read(方案 L2 起)·可用狀態:預覽(preview)

一次查一位監護人,回傳他目前生效中的監護關係裡的孩子,每個孩子帶 personId 與 POST /v1/persons:profiles 相同的五個基本資料欄位:givenName、familyName、displayName、 birthDate、gender。五個欄位一定出現,沒有值時是 null,檢查規則也與 POST /v1/persons:profiles 相同。

只限機器流程(workload token)。授權服務每次呼叫記一筆稽核紀錄。

冪等:唯讀,可以安全重送。

參數

名稱 位置 必填 型別 說明
personId path 是 string 監護人:psn_ person id,或訂單 customerId 帶的裸 UUID(舊系統的拼法,同一個人)。 UUID 必須是帶連字號的 8-4-4-4-12 形式,大小寫皆可;其他形式回 404。 最長 128

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "guardian": {
    "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
  },
  "wards": [
    {
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
      "givenName": "小明",
      "familyName": "王",
      "displayName": "王小明",
      "birthDate": "2019-04-07",
      "gender": "male"
    },
    {
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6d",
      "givenName": null,
      "familyName": null,
      "displayName": "新孩子",
      "birthDate": null,
      "gender": null
    }
  ],
  "truncated": false
}

POST /v1/line-targets

operationId listLineTargets 能力 lightup.line.target

能力:lightup.line.target(方案 L2 起)·可用狀態:預覽(preview)

一次最多 100 位客戶。每位回一個結果;DELIVERABLE 時帶 lineUserId, 其他結果一律不帶。

lineUserId 是這位客戶在該租戶自己的 LINE 官方帳號下的 LINE user id: 只能用那一個官方帳號送訊息給他,換到別的官方帳號沒有意義。

outcome 意思
DELIVERABLE 可以送,lineUserId 是要送的對象
NO_LINE 這位客戶沒有 LINE 身分
NOT_FOUND 這個租戶沒有這個 id 的客戶
AMBIGUOUS 這位客戶有不只一個 LINE id,或彼此不一致。平台不替你選,兩邊都不要送
BLOCKED 這位客戶已被封鎖(例如員工在聊天室封鎖),不要送
UNSUBSCRIBED 這位客戶取消訂閱,不要送

只限機器流程(workload token)。personIds 是 1–100 個 psn_ TypeID;有一個不合格就整個 422 schema_invalid。

冪等:唯讀,可以安全重送。結果反映當下的狀態,不要長期快取。

請求 body

application/json,schema PersonIdsRequest,必填。

範例 default

{
  "personIds": [
    "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
  ]
}

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "targets": [
    {
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
      "outcome": "DELIVERABLE",
      "lineUserId": "U0123456789abcdef0123456789abcdef"
    }
  ]
}

PUT /v1/persons/{personId}/tags/{tagId}

operationId putPersonTag 能力 lightup.tag.write

能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)

租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。

為一位客戶加上一個標籤。已經帶著 → 200 changed: false。

冪等(必讀)

Idempotency-Key 必填,而且必須是非 nil 的 UUID(與訂單的規則不同)。缺漏或不是 UUID → 422 schema_invalid,在判權之前。同一個 key 再送一次 → 200 replayed: true,不會再寫一次; 同一個 key 用在不同的寫入上 → 409 idempotency_key_reused。

其他

只限機器流程(workload token)。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
tagId path 是 TagId 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64
Idempotency-Key header 是 string 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid

回應

狀態 說明
200 已處理(changed 說明這次有沒有真的加上)
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:
422 標籤請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種新的代碼:
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

DELETE /v1/persons/{personId}/tags/{tagId}

operationId deletePersonTag 能力 lightup.tag.write

能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)

租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。

移除一位客戶的一個標籤。本來就沒帶著 → 200 changed: false。

Idempotency-Key 必填,必須是非 nil 的 UUID;規則與 PUT 相同(同一個 key 重送 → replayed: true;用在不同的寫入上 → 409 idempotency_key_reused)。404 與 409 的情況也與 PUT 相同。

只限機器流程(workload token)。

參數

名稱 位置 必填 型別 說明
personId path 是 PersonTypeId 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
tagId path 是 TagId 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64
Idempotency-Key header 是 string 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid

回應

狀態 說明
200 已處理(changed 說明這次有沒有真的移除)
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/tags/{tagId}/members:add

operationId addTagMembers 能力 lightup.tag.write

能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)

租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。

一次最多 1000 位客戶。回應說明多少位這次加上(changed)、多少位本來就帶著(unchanged), 並逐一列出被略過的客戶與原因(skipped):

reason 意思
missing 這個租戶沒有這位客戶
not_canonical 這位客戶已被合併到另一位;改用合併後的 person id
tag_limit 這位客戶的標籤數已達上限

provenance 選填:一個不透明的來源參照(例如規則 id、匯入批次 id),[A-Za-z0-9._:-],1–128 字元。

Idempotency-Key 必填,必須是非 nil 的 UUID。同一個 key、同一份請求重送是安全的; 同一個 key 用在不同的請求上 → 409 idempotency_key_reused。一個 key 綁定一個完整的請求: 多一位或少一位客戶、換標籤、換 provenance、先加後移都算不同的請求,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。

只限機器流程(workload token)。

參數

名稱 位置 必填 型別 說明
tagId path 是 TagId 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64
Idempotency-Key header 是 string 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid

請求 body

application/json,schema TagMembersAddRequest,必填。

範例 default

{
  "personIds": [
    "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
  ],
  "provenance": "rule:7"
}

回應

狀態 說明
200 已處理
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/tags/{tagId}/members:remove

operationId removeTagMembers 能力 lightup.tag.write

能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)

租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。

一次最多 1000 位客戶。回應形狀與 members:add 相同(changed/unchanged/skipped)。

Idempotency-Key 必填,必須是非 nil 的 UUID;規則與 members:add 相同。

只限機器流程(workload token)。

參數

名稱 位置 必填 型別 說明
tagId path 是 TagId 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64
Idempotency-Key header 是 string 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid

請求 body

application/json,schema PersonIdsBatchRequest,必填。

範例 default

{
  "personIds": [
    "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
  ]
}

回應

狀態 說明
200 已處理
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
409 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

POST /v1/tags

operationId createTag 能力 lightup.tag.define

能力:lightup.tag.define(方案 L2 起)·可用狀態:預覽(preview)

建立標籤不受成員寫入的切換限制(tag_writes_not_open),租戶切換身分之前也可以呼叫。

在一個已經存在的標籤分類(categoryNodeId,來自 POST /v1/categories:lookup)下建立標籤。 分類不存在 → 422 category_not_found;分類請由租戶在後台建立。

同一個分類下同一個名稱只會有一個標籤,所以重送是安全的,不需要 Idempotency-Key:

情境 結果
這次建立了新標籤 201,created: true
這個分類下已經有同名標籤 200,created: false,回傳既有那一個的 tagId
這個名稱對應的標籤 id 已被一個後來改名或搬走的標籤占用 409 tag_name_conflict

tagName 會先去掉前後空白,再檢查 1–100 字元、不含控制字元。description 去掉前後空白後為空, 視同沒給。

只限機器流程(workload token)。

請求 body

application/json,schema TagCreateRequest,必填。

範例 default

{
  "tagName": "永和 週六",
  "categoryNodeId": "node-7",
  "backgroundColor": "#12AB9F"
}

回應

狀態 說明
200 這個分類下已有同名標籤,回傳它的 id
201 已建立新標籤
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
409 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:
422 標籤請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種新的代碼:
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

GET /v1/line-message-groups

operationId findLineMessageGroups 能力 lightup.line.message_group.read

能力:lightup.line.message_group.read(方案 L2 起)·可用狀態:預覽(preview)

回傳租戶的 LINE 訊息組中,去掉前後空白後的名稱與 name 完全相同的那些,依 id 排序, 最多 10 個。不是模糊搜尋:差一個字、多一個空格(中間的)都不算。

只限機器流程:必須是 workload token(service account)。使用者本人的 self token 會得到 403 profile_not_supported。

冪等:GET,天然冪等。

參數

名稱 位置 必填 型別 說明
name query 是 string 要找的訊息組名稱。這個操作只收這一個查詢參數,而且只能出現一次。 去掉前後空白後比對, 必須 1–200 個字元(以 Unicode 字元計);否則 422 schema_invalid。

回應

狀態 說明
200 OK(沒有符合的也是 200,matched 為 0)
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
422 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

200 範例

範例 default

{
  "name": "永和 週六 10:00 課前影片",
  "matched": 1,
  "truncated": false,
  "items": [
    {
      "id": "6f2d1c0e-9a77-4f39-9b1a-0b5d6a3e2f0c",
      "name": "永和 週六 10:00 課前影片",
      "updatedAt": "2026-10-18T09:30:15.250Z",
      "messages": [
        {
          "type": "text",
          "text": "明天見!",
          "complete": true
        },
        {
          "type": "video",
          "originalContentId": "m-1",
          "previewImageId": "m-2",
          "complete": true
        }
      ]
    }
  ]
}

GET /v1/line-message-groups/{groupId}

operationId getLineMessageGroup 能力 lightup.line.message_group.read

能力:lightup.line.message_group.read(方案 L2 起)·可用狀態:預覽(preview)

回傳一個 LINE 訊息組:名稱、更新時間與每一則訊息的文字或媒體 id。

只限機器流程(workload token)。

冪等:GET,天然冪等。

參數

名稱 位置 必填 型別 說明
groupId path 是 LineMessageGroupId LINE 訊息組的 id,來自 GET /v1/line-message-groups?name=… 的回應。1–64 個 [A-Za-z0-9_-] (從舊系統搬來的 id 原樣保留,所以不一定是 UUID);形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9_-]{1,64}$;最長 64

回應

狀態 說明
200 OK
401 token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
403 token 有效,但現在不准做這件事。重試不會變成允許——
404 資源不存在,或存在但呼叫端連它存不存在都不該知道。
429 限流。限流有兩層:tenant 與 service account/使用者
503 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

共用錯誤回應

Unauthorized

401 — token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 (例如把 ID token 或第一方 token 拿來用)。

error 一律是 invalid_token,不細分。 沒帶 token 與帶了壞 token 回同一個答案,aud 錯與簽章錯也回同一個答案——細分等於幫呼叫端 (包括攻擊者)確認哪一項才是錯的。真正的原因記在伺服器端, 用 x-request-id 查。

重新取得 token 再試。重試同一張 token 不會變成成功。

ℹ️ delegated 與 shared profile 的 token 不在這裡被擋:它們的簽章 是對的,會走完驗證再由授權決定拒絕,所以拿到的是 403 profile_not_supported。

範例 idTokenUsed — 拿 ID token 當 access token

{
  "error": "invalid_token",
  "message": "token is not an access token",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh2j"
}

Forbidden

403 — token 有效,但現在不准做這件事。重試不會變成允許—— 要改的是 grant、方案或請求本身。

error 是穩定代碼,逐字來自 Amygdala 的授權決定(ADR-004 D5)。 程式判斷用它,不要 parse message。

error 意思 怎麼修
client_unknown 這個 client id 不存在 重新登記 app
client_disabled client 存在但已被停用(status=disabled)。與 client_unknown 分開:前者是「被關掉了」,後者是「從來沒有」,處理方式不同 tenant 管理員重新啟用。停用對在途 token 也立即生效——下一個請求就擋
actor_unknown token 沒有指出誰在操作:self 缺 actor_account_id,或 workload 帶的 actor_account_id 不等於 sub 重新取一張 token。這代表簽發端有問題,請附 x-request-id 回報
tenant_suspended 租戶被停權。與呼叫端是誰、請求哪一項能力都無關——整個租戶的第三方存取都停,讀寫皆然 租戶要先恢復。重試沒有用;即使換一張 token 也一樣,簽發端同樣會拒
tenant_not_enabled 這個租戶的第三方整合沒有生效:該租戶的方案不含第三方整合,或租戶尚未在後台開啟它。講的是租戶這一側的狀態,與呼叫端是誰、請求哪一項能力無關。刻意不分辨是哪一個原因——對你來說下一步一樣,而分開講會洩漏客戶的方案等級 請洽該租戶的管理員。重試與換 token 都沒有用——簽發端對同一個租戶一樣拒(回 OAuth 的 invalid_client)。真的「現在判不了」會是 503 authorization_unavailable,那個才該重試
client_not_third_party 這個 client 不是第三方類別(是第一方或內部工具) 平台端問題;第三方不該拿到這種 client
profile_not_supported token 的 profile 不在 v1 範圍——delegated 與 shared 落在這裡 改用本人(self)或機器(workload)token;代理要等 v2
subject_revoked service account 或使用者 session 已被撤銷/停用 tenant 管理員重新啟用,或請使用者重新登入
epoch_changed token 的 actor_epoch 與帳號現值不符——帳號被撤權過 重新取一張 token
capability_not_granted tenant 沒把這項能力授權給這個 app tenant 管理員在後台加授權
plan_capability_excluded 租戶方案不含這項能力 升級方案
capability_not_in_token 能力有被授權,但這張 token 沒帶這個 scope 換一張帶足 scope 的 token
capability_unavailable 這項能力在本部署尚未開放(目錄狀態不是可呼叫) 看文件的可用狀態,等它上線
resource_type_mismatch 能力宣告的資源型別與你打的資源對不上 修正呼叫
tenant_mismatch 資源不屬於這張 token 的租戶 修正呼叫
no_relationship 租戶對這個人沒有有效關係 修正呼叫,或先建立關係
forbidden 兜底:Amygdala 回了本版 Gateway 不認識的 deny 代碼。仍然是拒絕,不會變成放行,也不會變成可重試的 503 回報並附上 x-request-id

⚠️ tenant_mismatch 與 no_relationship 打在 person 資源上時會變成 404, 不是 403——否則 403 與 404 的差別本身就是一支「這個 person 存不存在」的 探測器(ADR-004 D9)。不透露資源是否存在是刻意的。

ℹ️ tenant_suspended 與 tenant_not_enabled 都不折成 404,即使打在 person 資源上也一樣回 403。它們講的是你的租戶(停權/第三方整合沒有生效), 不是目標資源存不存在,所以據此推不出任何關於那個 person 的事—— 沒有要遮蔽的東西。反過來折成 404 會讓一個只是沒開整合的租戶 以為自己的人都不見了。

範例 missingCapability

{
  "error": "capability_not_granted",
  "message": "this application is not granted lightup.person.metadata.write",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh3k"
}

範例 planTooLow

{
  "error": "plan_capability_excluded",
  "message": "the tenant plan does not include this capability",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh4m"
}

NotFound

404 — 資源不存在,或存在但呼叫端連它存不存在都不該知道。 兩者刻意回同一個答案(ADR-004 D9)。

範例 default

{
  "error": "not_found",
  "message": "resource not found",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh5n"
}

Conflict

409 — 你和別人撞上了。沒有任何東西被寫入。 兩種:

本 API 用 409 表達所有衝突,不用 412。 RFC 9110 對失敗的前置條件 給的是 412;收斂成單一狀態碼讓 client 只要分辨 Problem.error 就夠。 「前置條件標頭根本沒帶或帶重複」不是衝突,是 428,見下。

範例 conflict

{
  "error": "revision_conflict",
  "message": "the resource was modified; re-read and retry",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh6p"
}

範例 alreadyExists

{
  "error": "already_exists",
  "message": "the extension already exists; read its ETag and use If-Match",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh7q"
}

PreconditionRequired

428 — 這個寫入沒有表明它的前置條件(RFC 6585 §3)。

PUT 必須恰好帶一個:If-Match: "<etag>"(更新)或 If-None-Match: *(建立)。DELETE 必須帶 If-Match。 兩個都沒帶、或 PUT 同時帶兩個,就是這個錯誤。

沒有任何東西被寫入,而且重試同樣的請求永遠是同樣的結果—— 這是 client 的 bug,不是暫時狀況。本 API 沒有無條件覆寫的操作: 那正是遺失更新的來源(計畫 §6)。

範例 missing — 兩個都沒帶

{
  "error": "precondition_required",
  "message": "provide exactly one of If-Match or If-None-Match",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh7q"
}

範例 both — 兩個都帶

{
  "error": "precondition_required",
  "message": "If-Match and If-None-Match are mutually exclusive",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh8r"
}

PayloadTooLarge

413 — 單筆 data 超過 16 KiB。縮小內容,或把大東西放在你自己的資料庫 (計畫 §6:平台 metadata 不存照片與無界列表)。

範例 default

{
  "error": "payload_too_large",
  "message": "extension data exceeds 16 KiB",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh8r"
}

UnprocessableEntity

422 — 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。

額度用盡不會刪任何資料。 既有資料照常可讀、可刪、可匯出。

範例 quota

{
  "error": "quota_exceeded",
  "message": "tenant reached 50000 records for this extension",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh9s"
}

範例 schema

{
  "error": "schema_invalid",
  "message": "data does not match the registered extension schema",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzj1t"
}

TooManyRequests

429 — 限流。限流有兩層:tenant 與 service account/使用者 (計畫 §7)。兩層都可能觸發,回應不會告訴你是哪一層。

看 Retry-After 再重試。合法的大量同步不會被丟棄,會被要求放慢 ——需要更高額度請升級方案,別用更多帳號繞過(那會在 tenant 層再撞一次)。

範例 default

{
  "error": "rate_limited",
  "message": "too many requests",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzj2u"
}

AuthorizationUnavailable

503 — 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:

error 什麼做不完
authorization_unavailable 拿不到授權決定——Amygdala 不可用、逾時,或下游資料面不可用
token_verification_unavailable 驗簽就做不完——JWKS 取不到,或 unknown kid 的有界重取失敗

兩者都不是拒絕。平台 fail-closed:判不了就不放行,而不是降級成只驗簽 (計畫 §5)。都可以重試,請用指數退避;Retry-After 是建議不是承諾。

403 和 503 永遠不會長得一樣:前者是「不准」,後者是「現在不知道」。

範例 default

{
  "error": "authorization_unavailable",
  "message": "authorization service temporarily unavailable; retry",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzj3v"
}

OrderConflict

409 — 訂單操作與現況衝突。沒有任何東西被寫入或改變。 三種:

error 意思 怎麼修
idempotency_key_reused 同一個 Idempotency-Key 之前用在一份不同的建單請求上(下游代碼 IDEMPOTENCY_KEY_REUSED) 換一個新的 key 建立另一筆訂單。同一筆意圖的重送要用同一個 key 與同一份請求
request_in_progress 同一個 Idempotency-Key 的上一次請求還在處理中(下游代碼 IDEMPOTENCY_REQUEST_IN_PROGRESS)。回應帶 Retry-After: 2 等 Retry-After 秒後,用同一個 key、同一份請求重送
order_not_cancellable 取消時訂單不可取消。detail 是下游代碼與訊息,例如 ORDER_ALREADY_CANCELLED、ORDER_NOT_CANCELLABLE、ORDER_CANCEL_PENDING_OPERATOR 不要重試。讀 GET /v1/orders/{orderId} 確認現況

範例 idempotencyKeyReused

{
  "error": "idempotency_key_reused",
  "message": "this Idempotency-Key was used for a different request",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzk4w"
}

範例 orderNotCancellable

{
  "error": "order_not_cancellable",
  "message": "the order cannot be cancelled in its current state",
  "detail": "ORDER_ALREADY_CANCELLED: order is already cancelled",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzl5x"
}

OrderUnprocessable

422 — 請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種:

error 意思 怎麼修
schema_invalid 請求內容或標頭不符合該端點的 schema:未知欄位、必填缺漏、型別或範圍錯誤、格式不對的 id 或標頭(Idempotency-Key、X-LightUp-Operator、customerPersonId、expiresAt);也包括下游訂單服務回的 400(它沒有代碼) 照 OpenAPI 的 schema 修正請求。不要原樣重送
product_unavailable 訂單中有品項的 productId 在商品目錄裡不存在(下游代碼 ORD_019) 確認 productId 來自目錄,不要自行拼裝

取消端點的 422 只會是 schema_invalid(reason 缺漏、超過 500 字元,或帶了未知欄位)。

範例 productUnavailable

{
  "error": "product_unavailable",
  "message": "a product in this order does not exist in the catalogue",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzm6y"
}

TagConflict

409 — 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:

error 意思 怎麼修
tag_writes_not_open 這個租戶的客戶在這裡還不能寫標籤:租戶的身分切換尚未完成。這是狀態,不是權限 不要重試;等平台公告該租戶開放寫入
person_merged 這位客戶已被合併到另一位,路徑上的 person id 不是正本 改用合併後的 person id(例如重新 POST /v1/persons:resolve)再送
tag_name_conflict 建立標籤時,這個名稱在該分類下對應的標籤 id 已被一個後來改名或搬走的標籤占用 不要重試同一份請求;確認分類與名稱,或請租戶在後台整理該標籤

同一個 Idempotency-Key 用在不同的寫入上,也是 409,代碼是沿用的 idempotency_key_reused: 換一個新的 UUID 送另一個寫入;同一個寫入的重送要用同一個 key。

範例 tagWritesNotOpen

{
  "error": "tag_writes_not_open",
  "message": "tag writes are not open for this tenant yet",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzn7z"
}

範例 personMerged

{
  "error": "person_merged",
  "message": "the person was merged into another person",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzp8a"
}

TagUnprocessable

422 — 標籤請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種新的代碼:

error 意思 怎麼修
tag_limit_reached 這位客戶帶著的標籤數已達上限 先移除不用的標籤,不要原樣重送
category_not_found 建立標籤時指定的 categoryNodeId 不存在,或不是標籤分類 用 POST /v1/categories:lookup 取得分類 id;分類請由租戶在後台建立

請求本文、標頭或 id 不符合 schema 時仍是沿用的 schema_invalid(例如 Idempotency-Key 不是 UUID、 帶了未知欄位):照 OpenAPI 的 schema 修正請求,不要原樣重送。

範例 tagLimitReached

{
  "error": "tag_limit_reached",
  "message": "the person already holds the most tags allowed",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzq9b"
}

範例 categoryNotFound

{
  "error": "category_not_found",
  "message": "the tag category does not exist",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzr0c"
}

Schema

TokenRequest

application/x-www-form-urlencoded。三種 grant 各自需要的欄位不同, 所以用 oneOf 分開——送錯組合在 schema 層就看得出來,不必等伺服器回 400。

型別 —。

ClientCredentialsRequest

機器/背景。得到 workload token,沒有 refresh_token。 client_secret 可改放 Authorization: Basic;兩種擇一,不要同時送。

欄位 型別 必填 說明
grant_type string 是
client_id ClientId 是
client_secret string 否 service account 的機器憑證。用 client_secret_basic 時省略。 不要放進版本控制、前端 bundle 或 log。
scope ScopeString 否

未列出的欄位不被接受(additionalProperties: false)。

AuthorizationCodeRequest

使用者授權完成後,用一次性 code 換 token。得到 self token。 PKCE 必填——第三方 public 與 confidential client 都要。

欄位 型別 必填 說明
grant_type string 是
client_id ClientId 是
client_secret string 否 confidential client 才有;public client 不送。
code string 是 /oauth2/authorize 導回時帶的一次性授權碼。用過就失效。
code_verifier string 是 PKCE verifier,43–128 字元。授權請求送的是它的 S256 雜湊 (code_challenge),plain 不支援。 最長 128
redirect_uri string 是 必須與授權請求送出的那一個完全相同,且已登記在 client 上。 format uri

未列出的欄位不被接受(additionalProperties: false)。

RefreshTokenRequest

續期使用者 token。嚴格 rotation:每次成功都會換一張新的 refresh token,舊的立即失效;重放已消耗的那一張會殺掉整個 family (第三方不適用任何放寬,見 ADR-004 D1)。

欄位 型別 必填 說明
grant_type string 是
client_id ClientId 是
client_secret string 否 confidential client 才有。
refresh_token string 是 上一次回應給的那一張。不透明字串,不要解析。
scope — 否 可選,只能縮小原本的 scope,不能放大。省略就沿用原本的。

未列出的欄位不被接受(additionalProperties: false)。

ClientId

第三方 client id,形狀 tp_<tenant label>_<slug>,由 amygdala 配發。

型別 string。pattern ^tp_[a-z0-9]+(?:-[a-z0-9]+)*_[a-z0-9]+(?:-[a-z0-9]+)*$

ScopeString

以空白分隔的能力清單(OAuth 慣例,不是逗號)。 實際拿到的 scope 是各層交集後的結果,可能比請求的少—— 以回應的 scope 欄位為準,不要假設拿到的就是送出去的。

型別 string。

TokenResponse

RFC 6749 §5.1 的 token 回應。

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

未列出的欄位不被接受(additionalProperties: false)。

TokenError

RFC 6749 §5.2 的錯誤形狀。與本 API 其他端點的 Problem 不同—— 那是 OAuth 的既有契約,刻意保持原樣,不要把兩者混在同一個解析路徑。 /oauth2/revoke 與 /oauth2/introspect 的錯誤形狀相同但代碼集合不同, 用 OauthEndpointError——token 端點的 error 仍是這裡的四個封閉代碼。

欄位 型別 必填 說明
error string 是 列舉:invalid_client、invalid_grant、invalid_scope、unsupported_grant_type
error_description string 否 一般是給人看的說明,字串隨時可能改;程式判斷請用 error。 唯一的例外是契約明文列出的機器可讀值,目前只有一個: invalid_grant + error_description: tenant_suspended(租戶被停權, 簽發端拒絕發 token)。其他值不保證穩定。
message string 否 平台既有錯誤 body 的人類可讀欄位,實際回應會帶。 不是契約的一部分,字串與是否出現都可能改,不要解析它。

未列出的欄位不被接受(additionalProperties: false)。

OauthEndpointError

/oauth2/revoke 與 /oauth2/introspect 的錯誤形狀(同 RFC 6749 §5.2 的 error 形狀,不是 Problem)。代碼集合與 token 端點的 TokenError 不同, 所以另立一個 schema:不要把三者放進同一個解析路徑。 ℹ️ 來源與狀態:/oauth2/introspect 由 lightup-rs #1412 新增; /oauth2/revoke 是既有端點(discovery 公告為 revocation_endpoint), auth.lightup.tech 上的轉發同樣由 #1412 補上。#1412 已合併,amygdala 端自 amygdala-rs/v2.101.4 起在正式環境。

欄位 型別 必填 說明
error string 是 列舉:invalid_request、invalid_client、bad_request、slow_down、temporarily_unavailable、not_found
error_description string 否 給人看的說明,字串隨時可能改;程式判斷請用 error。
message string 否 平台既有錯誤 body 的人類可讀欄位。不是契約的一部分,不要解析它。

未列出的欄位不被接受(additionalProperties: false)。

IntrospectionResponse

RFC 7662 的 introspection 回應。非 active 時只有 active: false, 不分原因(不存在、過期、已消耗、別人的、背後 session 已結束都長一樣)。

欄位 型別 必填 說明
active boolean 是 這張 token 現在是否有效。false 時其他欄位都不會出現。
sub string 否 使用者的 psn_…(token 的 subject)。
sid string 否 OIDC session id;與 ID token 和 logout token 的 sid 相同。 32 個小寫十六進位字元(SHA-256 截斷),不是 UUID——不要拿它去 parse 成 UUID。 pattern ^[0-9a-f]{32}$
client_id string 否 一定等於呼叫端自己的 client id——查不到別人的 token。
token_type string 否 這張 token 是哪一種。access token 回 Bearer(RFC 6749 的 token type, 不是字串 access_token),refresh token 回 refresh_token。 列舉:Bearer、refresh_token
exp integer 否 到期時間(Unix 秒)。
iat integer 否 簽發時間(Unix 秒)。
auth_time integer 否 使用者當初登入的時間(Unix 秒),不是這次 refresh 的時間。
acr string 否 當初登入的 authentication context class。目前只有兩個值: urn:lightup:loa:1(一般登入)與 urn:lightup:loa:2(做過 step-up)。 列舉:urn:lightup:loa:1、urn:lightup:loa:2
tenant_id string 否 這張 token 所屬租戶。
scope string 否 空白分隔的有效 scope;為空時這個欄位不出現。

未列出的欄位不被接受(additionalProperties: false)。

Problem

所有錯誤共用的形狀(RFC 9457 的精神,欄位刻意極簡)。 error 是穩定代碼,程式判斷請用它;message 是給人看的,隨時可能改字。

欄位 型別 必填 說明
error string 是 穩定的機器可讀代碼。 列舉:invalid_token、client_unknown、client_disabled、actor_unknown、tenant_suspended、tenant_not_enabled、client_not_third_party、profile_not_supported、subject_revoked、epoch_changed、capability_not_granted、plan_capability_excluded、capability_not_in_token、capability_unavailable、resource_type_mismatch、tenant_mismatch、no_relationship、forbidden、not_found、revision_conflict、already_exists、precondition_required、payload_too_large、quota_exceeded、schema_invalid、rate_limited、idempotency_key_reused、request_in_progress、order_not_cancellable、product_unavailable、tag_writes_not_open、person_merged、tag_name_conflict、tag_limit_reached、category_not_found、authorization_unavailable、token_verification_unavailable
message string 否 人類可讀說明。不含資源是否存在的線索、內部路徑或任何秘密。
requestId string 是 同 x-request-id。回報問題請附上。
detail string 否 選填。目前只有 order_not_cancellable 使用,格式 "{code}: {message}",代碼與訊息來自下游 訂單服務。它不是 message 的同義詞;判斷請用 error。

未列出的欄位不被接受(additionalProperties: false)。

PersonTypeId

型別 string。pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$

TenantTypeId

型別 string。pattern ^ten_[0-9a-hjkmnp-tv-z]{26}$

ExtensionId

型別 string。pattern ^[a-z][a-z0-9_]{2,63}$

Capability

能力 id。完整清單是版本化的能力目錄(crates/lightup-types/capabilities.toml), 對外由文件網站發布,每項標明說明、資源型別、最低方案等級與可用狀態 (planned / preview / ga)。v1 的五項是 ga(2026-10-05 起); order.create、order.read、order.cancel 是 preview(2026-10-17 起); tag.read、person.resolve、line.target、line.message_group.read 是 preview(2026-10-19 起); person.profile.read 是 preview(2026-10-25 起); tag.write、tag.define 2026-10-19 起為 planned,2026-10-26 起為 preview; person.wards.read 是 preview(2026-10-28 起)。目前沒有公開的 planned 項目。

型別 string。pattern ^lightup\.[a-z][a-z0-9.]*$

Me

這張 token 代表誰。

欄位 型別 必填 說明
subjectType string 是 列舉:person、service_account
subjectId string 是 psn_…(person)或 acc_…(service account,kind=service)。
tenantId TenantTypeId 是
clientId string 是 第三方 client id,形狀 tp_<tenant label>_<slug>,全域唯一。 pattern ^tp_[a-z0-9]+(?:-[a-z0-9]+)*_[a-z0-9]+(?:-[a-z0-9]+)*$
scopes array<Capability> 是 這張 token 實際生效的能力(已經是各層交集後的結果)。
actor object 是 實際執行操作的帳號。
actor.accountId string 是 acc_…。人與 service account 同一個前綴,靠 subjectType 區分。

未列出的欄位不被接受(additionalProperties: false)。

Tenant

租戶的公開識別欄位。只有「這是誰」,沒有「它現在怎麼樣」。 不含租戶設定、方案等級、聯絡人、網域設定、社群 provider、LDAP, 也不含營運狀態(見下)。additionalProperties: false—— 內部欄位(例如 amygdala 的 slug)不會出現在這裡。

欄位 型別 必填 說明
tenantId TenantTypeId 是
displayName string 是

未列出的欄位不被接受(additionalProperties: false)。

Person

最少欄位。要更多欄位是新的能力與新的 grant,不是在這裡加參數。

欄位 型別 必填 說明
personId PersonTypeId 是
displayName string 是 顯示名稱。不保證唯一,也不是身分證明。 可能是空字串:這個人存在,只是平台上沒有任何可用的名字(尚未填、或只有 空白字元)。空字串不代表查不到這個人——查不到是 404——所以請不要把它當成 錯誤處理,要顯示的話自己用 personId 或你自己的資料補。
createdAt string 是 這個人在平台上的建立時間。 format date-time

未列出的欄位不被接受(additionalProperties: false)。

PersonExtensionWrite

寫入內容。data 整筆取代。 不要放照片、逐題事件、無界列表,或任何被當成權限/餘額/權益/身份綁定的欄位。

欄位 型別 必填 說明
schemaVersion integer 是 必須是這個 extension 登記過的版本之一。 最小 1
data object 是 序列化後 ≤ 16 KiB,超過回 413。

未列出的欄位不被接受(additionalProperties: false)。

PersonExtension

欄位 型別 必填 說明
extensionId ExtensionId 是
personId PersonTypeId 是
schemaVersion integer 是 最小 1
etag string 是 同回應的 ETag 標頭。寫入時原封不動放進 If-Match。
data object 是
createdAt string 是 format date-time
updatedAt string 是 format date-time
updatedBy string 是 最後寫入的 client id(不是使用者)。 要追到人,用 x-request-id 查稽核紀錄。

未列出的欄位不被接受(additionalProperties: false)。

PersonExtensionSummary

列表用的摘要,不含 data。要內容請用 key lookup 逐筆取。

欄位 型別 必填 說明
extensionId ExtensionId 是
schemaVersion integer 是 最小 1
etag string 是
updatedAt string 是 format date-time
updatedBy string 是

未列出的欄位不被接受(additionalProperties: false)。

PersonExtensionPage

欄位 型別 必填 說明
items array<PersonExtensionSummary> 是 最多 100 筆
nextCursor string | null 是 還有下一頁時是不透明字串;沒有下一頁時是 null。不要解析它。

未列出的欄位不被接受(additionalProperties: false)。

OrderCreateRequest

POST /v1/orders 的請求本文。未知欄位一律 422 schema_invalid。 沒有單價欄位:價格永遠由商品目錄決定,呼叫端無法指定。

欄位 型別 必填 說明
customerPersonId PersonTypeId 是 買家(psn_ TypeID)。Gateway 把它換成下游訂單服務的客戶 id(同一個 UUID,不是另一套 id)。
items array<OrderLineRequest> 是 最多 50 筆
remark string 否 選填備註。 最長 1000
expiresAt string 否 選填付款期限(RFC 3339)。有給的話必須晚於現在、且不超過現在起 10 年,否則 422 schema_invalid。 沒給的話,訂單在 30 分鐘後自動取消。 format date-time

未列出的欄位不被接受(additionalProperties: false)。

OrderLineRequest

訂單的一個品項。

欄位 型別 必填 說明
productId string 是 商品目錄的 id。只使用平台給過你的值。 最長 128
quantity integer 是 最小 1;最大 999
attributes object 否 選填,品項的附加屬性(字串對字串,最多 20 組)。

未列出的欄位不被接受(additionalProperties: false)。

OrderCancelRequest

POST /v1/orders/{orderId}/cancel 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
reason string 是 取消原因。 最長 500

未列出的欄位不被接受(additionalProperties: false)。

Order

訂單的對外投影(lightup.order.read)。只有這些欄位。 下游訂單服務的其他欄位 (建立方式、付款細節、買家內部 id、品項的 sku/名稱與屬性定義)一律不出現。

欄位 型別 必填 說明
orderId string 是 訂單 id。之後的讀取與取消用它。 最長 128
orderNumber string 是 訂單編號,已是給人看的格式。
status string 是 訂單狀態,例如 PENDING。
paymentStatus string 是 付款狀態,例如 UNPAID。
total number 是 訂單總額。
netPaidTotal number 是 淨已付金額;未付款時為 0。
expiresAt string | null 是 付款期限(RFC 3339);訂單沒有期限時為 null。 format date-time
createdAt string 是 建立時間(RFC 3339)。 format date-time
items array<OrderItem> 是

未列出的欄位不被接受(additionalProperties: false)。

OrderItem

訂單的一個品項(對外投影)。

欄位 型別 必填 說明
productId string 是 商品目錄的 id。
quantity integer 是 數量。
unitPrice number 是 單價(取自商品目錄)。
lineTotal number 是 此品項的小計。

未列出的欄位不被接受(additionalProperties: false)。

TagId

標籤 id。只使用平台給過你的值,不要自行拼裝。

型別 string。pattern ^[A-Za-z0-9._-]{1,64}$;最長 64

CategoryNodeId

標籤分類的 id,來自 POST /v1/categories:lookup。1–128 個可見 ASCII 字元。

型別 string。pattern ^[!-~]{1,128}$;最長 128

LookupName

要查的名稱,1–200 字元。

型別 string。最長 200

PersonIdsRequest

POST /v1/persons:tags 與 POST /v1/line-targets 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
personIds array<PersonTypeId> 是 1–100 個 psn_ TypeID。有一個不合格,整個請求就是 422 schema_invalid。 最多 100 筆

未列出的欄位不被接受(additionalProperties: false)。

PersonIdsBatchRequest

POST /v1/tags/{tagId}/members:remove 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
personIds array<PersonTypeId> 是 1–1000 個 psn_ TypeID。有一個不合格,整個請求就是 422 schema_invalid。 最多 1000 筆

未列出的欄位不被接受(additionalProperties: false)。

TagMembersAddRequest

POST /v1/tags/{tagId}/members:add 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
personIds array<PersonTypeId> 是 1–1000 個 psn_ TypeID。有一個不合格,整個請求就是 422 schema_invalid。 最多 1000 筆
provenance string 否 選填。產生這批成員的來源參照(例如規則 id、匯入批次 id),平台不解讀它。 pattern ^[A-Za-z0-9._:-]{1,128}$;最長 128

未列出的欄位不被接受(additionalProperties: false)。

TagMember

帶著這個標籤的一位客戶。

欄位 型別 必填 說明
personId PersonTypeId 是
addedAt string 是 加上這個標籤的時間(RFC 3339)。 format date-time

未列出的欄位不被接受(additionalProperties: false)。

TagMembersPage

GET /v1/tags/{tagId}/members 的一頁,依 person id 排序。

欄位 型別 必填 說明
members array<TagMember> 是
next PersonTypeId 否 下一頁的 after;最後一頁沒有這個欄位。

未列出的欄位不被接受(additionalProperties: false)。

HeldTag

一位客戶帶著的一個標籤。

欄位 型別 必填 說明
tagId TagId 是
addedAt string 是 加上這個標籤的時間(RFC 3339)。 format date-time

未列出的欄位不被接受(additionalProperties: false)。

PersonTags

一位客戶與他帶著的標籤。

欄位 型別 必填 說明
personId PersonTypeId 是
tags array<HeldTag> 是

未列出的欄位不被接受(additionalProperties: false)。

PersonsTagsResponse

POST /v1/persons:tags 的回應。

欄位 型別 必填 說明
persons array<PersonTags> 是

未列出的欄位不被接受(additionalProperties: false)。

LookupOutcome

名稱查詢的結果,封閉集合:FOUND(剛好一個)、NOT_FOUND(沒有)、AMBIGUOUS(不只一個)。

型別 string。列舉:FOUND、NOT_FOUND、AMBIGUOUS

TagLookupRequest

POST /v1/tags:lookup 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
names array<LookupName> 是 最多 100 筆
categoryNodeId CategoryNodeId 否 選填。只在這一個標籤分類下找。

未列出的欄位不被接受(additionalProperties: false)。

TagLookupResult

一個名稱的查詢結果。

欄位 型別 必填 說明
name string 是 請求裡的那個名稱。
outcome LookupOutcome 是
tagId TagId 否 只有 FOUND 時出現。

未列出的欄位不被接受(additionalProperties: false)。

TagLookupResponse

POST /v1/tags:lookup 的回應。

欄位 型別 必填 說明
results array<TagLookupResult> 是

未列出的欄位不被接受(additionalProperties: false)。

CategoryLookupRequest

POST /v1/categories:lookup 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
names array<LookupName> 是 最多 100 筆

未列出的欄位不被接受(additionalProperties: false)。

CategoryLookupResult

一個分類名稱的查詢結果。

欄位 型別 必填 說明
name string 是 請求裡的那個名稱。
outcome LookupOutcome 是
categoryNodeId CategoryNodeId 否 只有 FOUND 時出現。
candidates array<CategoryNodeId> 否 只有 AMBIGUOUS 時出現:每一個叫這個名稱的分類 id。

未列出的欄位不被接受(additionalProperties: false)。

CategoryLookupResponse

POST /v1/categories:lookup 的回應。

欄位 型別 必填 說明
results array<CategoryLookupResult> 是

未列出的欄位不被接受(additionalProperties: false)。

PersonResolveRequest

POST /v1/persons:resolve 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
legacyIds array 是 1–500 個舊客戶 id,每個 1–128 字元。 最多 500 筆

未列出的欄位不被接受(additionalProperties: false)。

ResolvedLegacyId

一個舊客戶 id 的對應結果。

欄位 型別 必填 說明
legacyId string 是 請求裡的那個舊 id。
outcome string 是 封閉集合,見 POST /v1/persons:resolve 的說明。 列舉:RESOLVED、NOT_FOUND、AMBIGUOUS、INVALID
personId PersonTypeId 否 只有 RESOLVED 時出現。

未列出的欄位不被接受(additionalProperties: false)。

PersonResolveResponse

POST /v1/persons:resolve 的回應。

欄位 型別 必填 說明
results array<ResolvedLegacyId> 是

未列出的欄位不被接受(additionalProperties: false)。

PersonProfilesRequest

POST /v1/persons:profiles 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
ids array 是 1–500 個 id,每個 1–128 字元:裸的舊客戶 UUID 或 psn_ person id, 分辨方式與 POST /v1/persons:resolve 相同。沒有列表形式:要讀的每一位都要指名。 最多 500 筆

未列出的欄位不被接受(additionalProperties: false)。

PersonProfile

一個 id 的基本資料結果。只有 FOUND 時帶 personId 與五個基本資料欄位, 而且五個欄位一定出現、沒有值時是 null;其他結果只有 id 與 outcome。 不含電話、email 或地址。

欄位 型別 必填 說明
id string 是 請求裡的那個 id,原樣回傳。
outcome string 是 封閉集合,見 POST /v1/persons:profiles 的說明。 列舉:FOUND、NOT_FOUND、AMBIGUOUS、INVALID
personId PersonTypeId 否 只有 FOUND 時出現。
givenName string | null 否 名字。只有 FOUND 時出現;沒有值時是 null。 最長 200
familyName string | null 否 姓氏。只有 FOUND 時出現;沒有值時是 null。 最長 200
displayName string | null 否 顯示名稱。只有 FOUND 時出現;沒有值時是 null。新系統建立的孩子常常只有這一個名稱, givenName、familyName 都是 null 時請改用它。 最長 200
birthDate string | null 否 生日,YYYY-MM-DD。只有 FOUND 時出現;沒有值或不是真實日期時是 null。 pattern ^\d{4}-\d{2}-\d{2}$;format date
gender string | null 否 性別,封閉集合。只有 FOUND 時出現;沒有值或不在集合內時是 null。 列舉:male、female、other、unknown、null

未列出的欄位不被接受(additionalProperties: false)。

PersonProfilesResponse

POST /v1/persons:profiles 的回應。

欄位 型別 必填 說明
profiles array<PersonProfile> 是

未列出的欄位不被接受(additionalProperties: false)。

PersonWard

一個孩子。personId 與五個基本資料欄位一定出現,沒有值時是 null, 規則與 POST /v1/persons:profiles 的 FOUND 結果相同。不含電話、email 或地址。

欄位 型別 必填 說明
personId PersonTypeId 是
givenName string | null 是 名字;沒有值時是 null。 最長 200
familyName string | null 是 姓氏;沒有值時是 null。 最長 200
displayName string | null 是 顯示名稱;沒有值時是 null。新系統建立的孩子常常只有這一個名稱, givenName、familyName 都是 null 時請改用它。 最長 200
birthDate string | null 是 生日,YYYY-MM-DD;沒有值或不是真實日期時是 null。 pattern ^\d{4}-\d{2}-\d{2}$;format date
gender string | null 是 性別,封閉集合;沒有值或不在集合內時是 null。 列舉:male、female、other、unknown、null

未列出的欄位不被接受(additionalProperties: false)。

AnalyticsAnswer

一個報表指標。都是彙總數字,不含個人資料。

欄位 型別 必填 說明
meta object 是
meta.topic string 是
meta.metric string 是
meta.granularity string 是
meta.timezone string 是
meta.currency string 是
meta.rangeStart string 是 範圍起點(含),租戶時區的日期。
meta.rangeEnd string 是 範圍終點(不含),租戶時區的日期。
meta.compareStart string 否
meta.compareEnd string 否
meta.isPartial boolean 是 true 表示有部分資料讀取失敗,數字可能偏低。
meta.generatedAt string 是
meta.notes array 是 這批數字的限制,請一併讀取。
schema array 是 rows 裡每個 key 的定義。
rows array 是
series array 是

未列出的欄位不被接受(additionalProperties: false)。

AnalyticsMetricList

這個報表領域開放的指標。

欄位 型別 必填 說明
metrics array 是

未列出的欄位不被接受(additionalProperties: false)。

PersonWardsResponse

GET /v1/persons/{personId}/wards 的回應。

欄位 型別 必填 說明
guardian object 是 平台找到的監護人。
guardian.personId PersonTypeId 是
wards array<PersonWard> 是 目前生效中的監護關係裡的孩子,最多 50 個。沒有孩子時是空陣列。 最多 50 筆
truncated boolean 是 孩子超過 50 個、只回了前 50 個時是 true。

未列出的欄位不被接受(additionalProperties: false)。

LineTarget

一位客戶的 LINE 投遞結果。

欄位 型別 必填 說明
personId PersonTypeId 是
outcome string 是 封閉集合,見 POST /v1/line-targets 的說明。 列舉:DELIVERABLE、NO_LINE、NOT_FOUND、AMBIGUOUS、BLOCKED、UNSUBSCRIBED
lineUserId string 否 只有 DELIVERABLE 時出現。 這位客戶在該租戶自己的 LINE 官方帳號下的 LINE user id; 只能用那一個官方帳號送訊息,換到別的官方帳號沒有意義。

未列出的欄位不被接受(additionalProperties: false)。

LineTargetsResponse

POST /v1/line-targets 的回應。

欄位 型別 必填 說明
targets array<LineTarget> 是

未列出的欄位不被接受(additionalProperties: false)。

TagMembershipChange

單一成員寫入(PUT/DELETE /v1/persons/{personId}/tags/{tagId})的結果。

欄位 型別 必填 說明
changed boolean 是 這次呼叫真的加上(或移除)了這個成員關係。
replayed boolean 是 同一個 Idempotency-Key 之前已經套用過;這次沒有再寫入。

未列出的欄位不被接受(additionalProperties: false)。

SkippedPerson

批次寫入時被略過的一位客戶。

欄位 型別 必填 說明
personId PersonTypeId 是
reason string 是 封閉集合:missing(租戶沒有這位客戶)、not_canonical(已被合併)、tag_limit(標籤數已達上限)。 列舉:missing、not_canonical、tag_limit

未列出的欄位不被接受(additionalProperties: false)。

TagMembersBatchResult

批次成員寫入(members:add/members:remove)的結果。

欄位 型別 必填 說明
changed integer 是 這次真的加上(或移除)的客戶數。 最小 0
unchanged integer 是 本來就是要求的狀態、這次沒有改變的客戶數。 最小 0
skipped array<SkippedPerson> 是 被略過的每一位客戶與原因。
replayed boolean 是 true:這批(或其中一部分)先前已用同一個 Idempotency-Key 套用過,這次沒有重做。 平台不保存第一次的回應,所以已套用的那部分不會再出現在 changed/unchanged/skipped 裡; 需要完整的略過名單,請以第一次收到的回應為準,或改用 POST /v1/persons:tags 查目前狀態。

未列出的欄位不被接受(additionalProperties: false)。

TagCreateRequest

POST /v1/tags 的請求本文。未知欄位一律 422 schema_invalid。

欄位 型別 必填 說明
tagName string 是 標籤名稱。先去掉前後空白,再檢查 1–100 字元、不含控制字元。 最長 100
categoryNodeId CategoryNodeId 是 一個已經存在的標籤分類。不存在 → 422 category_not_found。
backgroundColor string 否 選填,#RRGGBB。 pattern ^#[0-9A-Fa-f]{6}$
description string 否 選填,最多 500 字元(去掉前後空白後計算;為空視同沒給)。 最長 500

未列出的欄位不被接受(additionalProperties: false)。

TagCreated

POST /v1/tags 的回應。

欄位 型別 必填 說明
tagId TagId 是
created boolean 是 true = 這次建立(201);false = 這個分類下已有同名標籤,回傳的是它(200)。

未列出的欄位不被接受(additionalProperties: false)。

LineMessageGroupId

LINE 訊息組 id。只使用平台給過你的值,不要自行拼裝。

型別 string。pattern ^[A-Za-z0-9_-]{1,64}$;最長 64

LineMessage

訊息組裡的一則訊息(對外投影)。只有這些欄位。 | type | 帶什麼 | |---|---| | text | text | | image、video | originalContentId、previewImageId:媒體 id,不是網址 | | 其他(或 null) | 只有 type 與 complete: false | complete 為 false 時不要送出這個訊息組:表示這則訊息有平台沒有交給你的部分 (本版不認得的訊息類型,或多出來的欄位),照著送出去會和原本的內容不一樣。

欄位 型別 必填 說明
type string | null 是 訊息類型,例如 text、image、video。存的訊息沒有類型時是 null。
complete boolean 是 這則訊息的內容是否完整交給你了。false → 整個訊息組都不要送。
text string 否 只有 type: text 時出現。訊息文字。
originalContentId string 否 只有 type: image/video 時出現。原始媒體的 id(不是網址)。
previewImageId string 否 只有 type: image/video 時出現。預覽圖的 id(不是網址)。

未列出的欄位不被接受(additionalProperties: false)。

LineMessageGroup

一個 LINE 訊息組(對外投影,lightup.line.message_group.read)。

欄位 型別 必填 說明
id LineMessageGroupId 是
name string 是 訊息組名稱。
updatedAt string 是 最後更新時間(RFC 3339,UTC,毫秒精度)。 format date-time
messages array<LineMessage> 是 依原本的順序。

未列出的欄位不被接受(additionalProperties: false)。

LineMessageGroupMatches

GET /v1/line-message-groups?name=… 的回應。

欄位 型別 必填 說明
name string 是 比對用的名稱(去掉前後空白後)。
matched integer 是 回來的訊息組數,等於 items 的長度。 最小 0;最大 10
truncated boolean 是 true = 符合的不只回來的這些(上限 10 個)。
items array<LineMessageGroup> 是 名稱完全相同的訊息組,依 id 排序。 最多 10 筆

未列出的欄位不被接受(additionalProperties: false)。

安全機制

bearerAuth

LightUp profile-v2 access token。Authorization: Bearer <token>。

Gateway 驗這些,缺一不可:

用錯 token(ID token、第一方 storefront token、內部 x-system-token)一律 401。

oauth2AuthorizationCode

使用者授權(互動式)。public client 強制 PKCE S256; 第三方 confidential client 也必填 PKCE(不吃第一方的相容路徑)。

發出的 token 是 profile v2 self——代表登入的本人,而且只有本人。 v1 不簽發代理(delegated)token,同意頁也沒有「選擇被代理對象」這一步。 refresh 走嚴格 rotation:重放已消耗的 refresh 會殺掉整個 family。 第三方不會拿到 reuse grace、sliding 或 absolute-max 放寬。

flow authorizationCode

scope 說明
lightup.profile.self.read 讀這張 token 代表的身分
lightup.person.read 讀獲授權人員的最少欄位
lightup.person.metadata.read 讀本 app 自己的人員 metadata
lightup.person.metadata.write 寫/刪本 app 自己的人員 metadata
lightup.tenant.info.read 讀租戶公開識別欄位

oauth2ClientCredentials

機器/背景操作。主體是 service account,不是 client: client 憑證證明「哪支程式」,token 的 sub 是租戶的 service account (acc_…,AccountKind::Service——與人使用同一個 id 前綴)。

發出的 token 是 profile v2 workload,TTL 15 分,沒有 refresh (到期就重新換一張)。

實際 scope = 請求的 scope ∩ service account 的 grantedCapabilities ∩ 租戶方案上限。交集為空 → invalid_scope,不會發一張沒有 scope 的 token。

憑證輪替:建立 next secret → 兩把並存最長 7 天 → promote,舊的立即失效。 撤銷:停用帳號或推進 epoch,在途 token 在下一個請求即失效。

client_credentials 只在部署開啟第三方整合時才被 /oauth2/token 接受, discovery 的 grant_types_supported 也只在那時公告它(ADR-004 D3)。

flow clientCredentials

scope 說明
lightup.profile.self.read 讀這張 token 代表的 service account
lightup.person.read 讀獲授權人員的最少欄位
lightup.person.metadata.read 讀本 app 自己的人員 metadata
lightup.person.metadata.write 寫/刪本 app 自己的人員 metadata
lightup.tenant.info.read 讀租戶公開識別欄位
lightup.order.create 以目錄價格為租戶的客戶建立未付款訂單(僅機器流程)
lightup.order.read 讀取本 app 建立的訂單狀態、金額與付款狀態(僅機器流程)
lightup.order.cancel 取消本 app 建立的未付款訂單(僅機器流程)
lightup.tag.read 讀租戶的客戶帶著哪些標籤、帶著某標籤的客戶,並以名稱查標籤與標籤分類(僅機器流程)
lightup.person.resolve 把租戶的舊客戶 id 對應到 person id(僅機器流程)
lightup.line.target 讀租戶的客戶能不能用 LINE 聯絡;能的話,回傳他在該租戶自己的 LINE 官方帳號下的 LINE user id(僅機器流程)
lightup.tag.write 為客戶加上、移除租戶的標籤(僅機器流程)
lightup.tag.define 在租戶既有的標籤分類下建立標籤(僅機器流程)
lightup.line.message_group.read 以 id 或完整名稱讀取租戶的 LINE 訊息組:每則訊息的文字與媒體 id(僅機器流程)
lightup.person.profile.read 以 id 讀取租戶指名客戶的名字、姓氏、顯示名稱、生日與性別(僅機器流程)
lightup.person.wards.read 列出租戶的某位客戶目前監護中的孩子,附每個孩子的基本資料(僅機器流程)
lightup.analytics.traffic.read 讀取租戶的網站流量與結帳漏斗報表(彙總,僅機器流程)