LightUp Third-Party API — English summary
The full documentation is written in Traditional Chinese. This page is the English summary: enough to decide whether the API fits, and enough to read the machine-readable contract on your own. For anything that matters operationally, read the Chinese page it links to — that is the normative text.
Contract status: Accepted (settled, implementation merged and live).
The endpoints are live: the API host accepts requests, and so do the third-party sign-in, token, introspection and logout endpoints on
auth.lightup.tech. Integration takes effect tenant by tenant — while a tenant's plan does not include it, or its administrator has not switched it on in the dashboard, every call is refused with403 tenant_not_enabled, and a fresh token does not change that.Every capability carries an
availability: planned, preview or generally available. All five v1 capabilities are generally available since 2026-10-05: the compatibility and deprecation policy applies to them. The three order capabilities added on 2026-10-17 (order.create,order.read,order.cancel) are preview: machine tokens only, and not yet covered by that policy. The tag and person capabilities added on 2026-10-19 (tag.read,person.resolve,line.target,tag.write,tag.define) are all preview, machine tokens only; the two writes moved there from planned on 2026-10-26. Membership writes answer409 tag_writes_not_openuntil the tenant's identity cutover is complete, so do not start writing them before it.line.message_group.read(LINE message groups), added the same day, is preview as well, machine tokens only.person.profile.read(customer profiles), added on 2026-10-25, is preview too, machine tokens only. The addresses are decided and live (api.lightup.techfor the API,developers.lightup.techfor this site).
What this API is
An API for customer applications that run outside the LightUp platform. LightUp's own products (app, dashboard, storefront) use their own BFFs and are not in scope here.
Base URL: https://api.lightup.tech/v1, decided on 2026-09-23. Two lookalike
hosts are not this API and will not accept these calls: api.app.lightup.tech is the
first-party app BFF and api.d.lightup.tech is the dashboard BFF. auth.lightup.tech
is part of this contract, but it is the login and token endpoint, not the API host.
The endpoint is live. Access takes effect tenant by tenant: until the tenant's plan
includes third-party integration and its owner has switched it on, every call is refused
with 403 tenant_not_enabled and the token endpoint refuses too, so retrying or fetching a
fresh token does not help. Ask the tenant owner to switch it on in the dashboard. The five original capabilities are generally available (ga) since 2026-10-05, so the
compatibility and deprecation policy applies to them. The three order capabilities added on 2026-10-17 are preview: see the section below. The five tag and person capabilities added on 2026-10-19 are preview: the three reads from the start, the two writes since 2026-10-26 (they were planned until then); membership writes are refused until the tenant's identity cutover is complete. See the section after it. The LINE message-group read added the same day is preview too: see the section after that. The customer-profile read added on 2026-10-25 (person.profile.read) is preview as well, machine tokens only (see the tags and persons section).
Authorization modes (v1)
| Mode | Grant | Token profile | Subject | TTL | Refresh |
|---|---|---|---|---|---|
| Machine / background | client_credentials |
workload |
service account (acc_…) |
15 min | none |
| End user, acting on their own data | authorization_code + PKCE (S256) |
self |
person (psn_…) |
15 min | yes, strict rotation |
There is no delegation in v1. Acting on behalf of another person (the delegated
profile) is v2 planning material. Sending your own user_id or x-user-* header is not
proof of delegation and the platform will not accept it.
Token validation
Every request is checked twice: locally, then against the platform's authorization service.
- ES256, keys from the fixed JWKS at
https://auth.lightup.tech/.well-known/jwks.json. The platform never fetches keys from a URL a token names. audislightup-api— not the client id.- JOSE header
typmust beat+jwt. An ID token is not an access token and is rejected here. - Then, on every request, the gateway asks the authorization service whether this client, this account, this grant, this plan and this resource still allow the call. There is no allow-cache in v1.
- If authorization cannot be determined, the gateway returns 503, never a signature-only pass. Fail-closed.
Capabilities
Scopes are named lightup.<capability>. The effective set is an intersection:
effective = tenant plan ∩ tenant's grant to this app ∩ account/user consent ∩ resource policy
Adding a capability to the catalogue does not widen an existing grant. Upgrading a plan does not widen an existing grant either.
| Capability | Resource | Min plan | Availability | What it does |
|---|---|---|---|---|
lightup.profile.self.read |
self | L1 | generally available | 讀這張 token 代表的 service account |
lightup.person.read |
person | L2 | generally available | 讀獲授權人員的最少欄位 |
lightup.person.metadata.read |
person | L2 | generally available | 讀本 app 自己的人員 metadata |
lightup.person.metadata.write |
person | L2 | generally available | 寫/刪本 app 自己的人員 metadata |
lightup.tenant.info.read |
tenant | L1 | generally available | 讀租戶公開識別欄位 |
lightup.order.create |
tenant | L2 | preview | 以目錄價格為租戶的客戶建立未付款訂單(僅機器流程) |
lightup.order.read |
tenant | L2 | preview | 讀取本 app 建立的訂單狀態、金額與付款狀態(僅機器流程) |
lightup.order.cancel |
tenant | L2 | preview | 取消本 app 建立的未付款訂單(僅機器流程) |
lightup.tag.read |
tenant | L2 | preview | 讀租戶的客戶帶著哪些標籤、帶著某標籤的客戶,並以名稱查標籤與標籤分類(僅機器流程) |
lightup.person.resolve |
tenant | L2 | preview | 把租戶的舊客戶 id 對應到 person id(僅機器流程) |
lightup.line.target |
tenant | L2 | preview | 讀租戶的客戶能不能用 LINE 聯絡;能的話,回傳他在該租戶自己的 LINE 官方帳號下的 LINE user id(僅機器流程) |
lightup.tag.write |
tenant | L2 | preview | 為客戶加上、移除租戶的標籤(僅機器流程) |
lightup.tag.define |
tenant | L2 | preview | 在租戶既有的標籤分類下建立標籤(僅機器流程) |
lightup.line.message_group.read |
tenant | L2 | preview | 以 id 或完整名稱讀取租戶的 LINE 訊息組:每則訊息的文字與媒體 id(僅機器流程) |
lightup.person.profile.read |
tenant | L2 | preview | 以 id 讀取租戶指名客戶的名字、姓氏、顯示名稱、生日與性別(僅機器流程) |
lightup.person.wards.read |
tenant | L2 | preview | 列出租戶的某位客戶目前監護中的孩子,附每個孩子的基本資料(僅機器流程) |
lightup.person.contact.read |
tenant | L2 | planned | 以 id 讀取租戶指名客戶已驗證的登入手機與 email,以及各自的驗證時間 |
lightup.person.search |
tenant | L2 | planned | 以完整的 email 或手機號碼精確查詢租戶的客戶,只回 person id |
lightup.person.list |
tenant | L2 | planned | 依更新時間分頁列出租戶的客戶(只回 person id 與更新時間) |
lightup.person.write |
tenant | L2 | planned | 建立沒有登入識別的客戶,並修改名字、姓氏、顯示名稱、生日與性別 |
lightup.person.wards.write |
tenant | L2 | planned | 建立、修改與解除租戶的監護關係 |
lightup.person.marketing_consent.read |
tenant | L2 | planned | 以 id 讀取租戶指名客戶的行銷同意狀態 |
lightup.person.marketing_consent.write |
tenant | L2 | planned | 記錄或撤回客戶的行銷同意(必須帶同意時間與來源管道) |
lightup.audience.read |
tenant | L2 | planned | 讀取租戶的分眾群組與成員 |
lightup.audience.write |
tenant | L2 | planned | 建立與修改租戶的分眾群組與成員 |
lightup.membership.read |
tenant | L2 | planned | 讀取租戶的會員方案與客戶的會員資格 |
lightup.membership.write |
tenant | L2 | planned | 授予、修改與終止客戶的會員資格 |
lightup.loyalty.read |
tenant | L2 | planned | 讀取租戶的會員等級、客戶點數餘額與紀錄 |
lightup.loyalty.points.write |
tenant | L2 | planned | 發放與扣除客戶的點數 |
lightup.loyalty.tier.write |
tenant | L2 | planned | 修改租戶的會員等級 |
lightup.coupon.read |
tenant | L2 | planned | 讀取租戶的優惠券與使用紀錄 |
lightup.coupon.write |
tenant | L2 | planned | 建立與修改租戶的優惠券 |
lightup.product.read |
tenant | L2 | planned | 讀取租戶的商品、價格與分類 |
lightup.product.write |
tenant | L2 | planned | 建立與修改租戶的商品、價格與分類 |
lightup.inventory.read |
tenant | L2 | planned | 讀取租戶商品的庫存與可售數量 |
lightup.inventory.write |
tenant | L2 | planned | 調整租戶商品的庫存 |
lightup.order.list |
tenant | L2 | planned | 列出並讀取租戶的所有訂單(不限本應用程式建立的) |
lightup.order.update |
tenant | L2 | planned | 修改租戶的訂單:備註、付款前的品項與出貨狀態 |
lightup.order.refund |
tenant | L2 | planned | 為租戶已付款的訂單全額或部分退款 |
lightup.cart.read |
tenant | L2 | planned | 讀取租戶客戶尚未結帳的購物車 |
lightup.invoice.read |
tenant | L2 | planned | 讀取租戶訂單開立的發票 |
lightup.invoice.write |
tenant | L2 | planned | 開立、作廢與折讓租戶的發票 |
lightup.payment.read |
tenant | L2 | planned | 讀取租戶訂單的付款交易紀錄 |
lightup.subscription.read |
tenant | L2 | planned | 讀取租戶的訂閱方案與客戶的訂閱 |
lightup.subscription.write |
tenant | L2 | planned | 建立、修改與取消客戶的訂閱 |
lightup.course.read |
tenant | L2 | planned | 讀取租戶的課程、單元與報名 |
lightup.course.write |
tenant | L2 | planned | 建立與修改租戶的課程與單元 |
lightup.course.progress.read |
tenant | L2 | planned | 讀取租戶學員的學習進度 |
lightup.offering.read |
tenant | L2 | planned | 讀取租戶可預約的項目與時段 |
lightup.offering.write |
tenant | L2 | planned | 建立與修改租戶可預約的項目與時段 |
lightup.resource.read |
tenant | L2 | planned | 讀取租戶可預約的資源:場地、人員與設備 |
lightup.resource.write |
tenant | L2 | planned | 建立與修改租戶可預約的資源 |
lightup.reservation.read |
tenant | L2 | planned | 讀取租戶的預約 |
lightup.reservation.create |
tenant | L2 | planned | 替租戶的客戶建立預約 |
lightup.reservation.update |
tenant | L2 | planned | 修改與確認租戶的預約 |
lightup.reservation.cancel |
tenant | L2 | planned | 取消租戶的預約 |
lightup.reservation.transfer |
tenant | L2 | planned | 把預約改到別的時段或別的客戶 |
lightup.checkin.write |
tenant | L2 | planned | 記錄租戶預約的報到 |
lightup.form.read |
tenant | L2 | planned | 讀取租戶的表單與題目 |
lightup.form.record.read |
tenant | L2 | planned | 讀取租戶表單收到的填答 |
lightup.form.record.write |
tenant | L2 | planned | 修改租戶表單的填答 |
lightup.form.submit |
tenant | L2 | planned | 替租戶的客戶送出表單填答 |
lightup.line.message.send |
tenant | L2 | planned | 以租戶的 LINE 官方帳號傳訊息給客戶 |
lightup.line.broadcast |
tenant | L2 | planned | 對租戶的 LINE 受眾群發訊息 |
lightup.line.audience.read |
tenant | L2 | planned | 讀取租戶的 LINE 受眾 |
lightup.line.audience.write |
tenant | L2 | planned | 建立與修改租戶的 LINE 受眾 |
lightup.message.send |
tenant | L2 | planned | 以單一呼叫經 LINE、簡訊或 email 傳訊息給租戶的客戶,由平台選擇管道 |
lightup.email.template.read |
tenant | L2 | planned | 讀取租戶的 email 範本 |
lightup.email.template.write |
tenant | L2 | planned | 建立與修改租戶的 email 範本 |
lightup.execution_plan.read |
tenant | L2 | planned | 讀取租戶的排程發送計畫與結果 |
lightup.execution_plan.write |
tenant | L2 | planned | 建立與修改租戶的排程發送計畫 |
lightup.execution_plan.execute |
tenant | L2 | planned | 執行、放行與重試租戶的排程發送計畫 |
lightup.chatroom.read |
tenant | L2 | planned | 讀取租戶的客服對話與訊息 |
lightup.chatroom.message.send |
tenant | L2 | planned | 在租戶的客服對話中傳送訊息 |
lightup.chatroom.assign |
tenant | L2 | planned | 把租戶的客服對話指派給同仁 |
lightup.calendar.read |
tenant | L2 | planned | 讀取租戶的行事曆與事件 |
lightup.calendar.write |
tenant | L2 | planned | 在租戶的行事曆建立與修改事件 |
lightup.calendar.busy.read |
tenant | L2 | planned | 讀取租戶同仁的忙碌時段(不含事件內容) |
lightup.file.read |
tenant | L2 | planned | 讀取租戶的檔案 |
lightup.file.write |
tenant | L2 | planned | 上傳與刪除租戶的檔案 |
lightup.link.read |
tenant | L2 | planned | 讀取租戶的短網址與點擊數 |
lightup.link.write |
tenant | L2 | planned | 建立與修改租戶的短網址 |
lightup.task.read |
tenant | L2 | planned | 讀取租戶的任務卡 |
lightup.task.write |
tenant | L2 | planned | 建立與修改租戶的任務卡 |
lightup.page.read |
tenant | L2 | planned | 讀取租戶的前台頁面 |
lightup.page.write |
tenant | L2 | planned | 建立與修改租戶前台頁面的草稿 |
lightup.page.publish |
tenant | L2 | planned | 發佈租戶的前台頁面 |
lightup.automation.flow.read |
tenant | L2 | planned | 讀取租戶的自動化流程 |
lightup.automation.flow.write |
tenant | L2 | planned | 建立與修改租戶的自動化流程 |
lightup.automation.flow.publish |
tenant | L2 | planned | 發佈與封存租戶的自動化流程 |
lightup.ledger.read |
tenant | L2 | planned | 讀取租戶的會計帳:科目、傳票與餘額 |
lightup.report.read |
tenant | L2 | planned | 讀取租戶的報表 |
lightup.report.export |
tenant | L2 | planned | 把租戶的報表匯出成檔案 |
lightup.analytics.revenue.read |
tenant | L2 | planned | 讀取租戶的營收與商品銷售報表(彙總) |
lightup.analytics.traffic.read |
tenant | L2 | preview | 讀取租戶的網站流量與結帳漏斗報表(彙總,僅機器流程) |
lightup.analytics.ads.read |
tenant | L2 | planned | 讀取租戶的廣告花費與成效報表(彙總) |
lightup.analytics.customers.read |
tenant | L2 | planned | 讀取租戶的顧客成長與留存報表(彙總) |
lightup.analytics.messaging.read |
tenant | L2 | planned | 讀取租戶的訊息量與送達報表(彙總) |
lightup.analytics.support.read |
tenant | L2 | planned | 讀取租戶的客服量與回覆時間報表(彙總,不含個別同仁) |
lightup.analytics.loyalty.read |
tenant | L2 | planned | 讀取租戶的點數與會員報表(彙總) |
lightup.analytics.lms.read |
tenant | L2 | planned | 讀取租戶的課程進度報表(彙總) |
lightup.analytics.engagement.read |
tenant | L2 | planned | 讀取租戶的表單填寫與短網址報表(彙總) |
lightup.settings.read |
tenant | L2 | planned | 讀取租戶的公開設定 |
Revocation
Revocation takes effect on the next request. No numeric propagation bound is published and there is no SLA on it: the promise is the trigger, not a number. Token TTL is a ceiling, not a revocation mechanism.
Sign-out, revocation and introspection
Status, 2026-09-30. Everything in this section is live (lightup-rs #1408, #1412, #1425 and #1431). It describes current behaviour, not a plan.
Three different things, deliberately kept apart:
| What you do | Scope |
|---|---|
POST https://auth.lightup.tech/oauth2/revoke (RFC 7009) |
Revokes only your own client's refresh token family. It does not end the person's sign-in and sends no back-channel logout; other applications keep working |
GET|POST https://auth.lightup.tech/oauth2/logout (RP-Initiated Logout) |
Ends the sign-in session and sends back-channel logout to every third-party client holding tokens from it, including yours. id_token_hint is required; post_logout_redirect_uri must match a registered value exactly |
POST https://auth.lightup.tech/oauth2/introspect (RFC 7662) |
Changes nothing; answers whether a token is valid right now. Read live, no cache — this is the authoritative source |
- Token endpoint, suspended tenant. An
authorization_codeorrefresh_tokenexchange for a suspended tenant answers400 {"error":"invalid_grant","error_description":"tenant_suspended"}— the RFC 6749 error shape, not a 403Problem. That is the oneerror_descriptionvalue that is machine-readable; the rest are prose that may change. Amessagefield may also appear and is not part of the contract. (From #1408; #1412 extends it to the refresh path.) - Introspection response fields, exactly as the platform returns them.
token_typeisBearerfor an access token — not the stringaccess_token— andrefresh_tokenfor a refresh token.sidis 32 lowercase hex characters (a truncated SHA-256), not a UUID.acris one ofurn:lightup:loa:1andurn:lightup:loa:2. - Introspection is restricted. Only an enabled, confidential third-party client
may call it, and only for its own tokens. Anything else is
{"active": false}, with no reason given. If the platform cannot decide, it answers 503 and neveractive: true— fail closed on your side too. - Introspection answers for user tokens only. A
client_credentials(service account) access token has no session behind it, and introspection is built around a live session, so it always answers{"active": false}for one — even while that token still works and the very next/v1/mereturns 200. For a machine token the authoritative revocation signal is the gateway's own decision: call/v1/*and read the answer, 200 for still allowed and 403 (subject_revoked,epoch_changed,capability_not_granted) for no longer. - Replaying a refresh token is treated as theft. It revokes the whole family and
ends the entire sign-in, signing the person out of every third-party application.
There is no retry grace: if a refresh call times out, introspect the old token instead of
resending it (
active: truemeans the refresh did not take effect and may be resent;active: falsemeans sign in again). - Logout registration is requested, not called. Post-logout redirect URIs and the
back-channel logout URI are registered by the tenant owner in the LightUp dashboard
(or by a platform operator over an internal route). Third parties never call that
internal API; you supply the values. Each submission replaces the whole set — an
omitted field is cleared. URIs must be https on a public domain — the host must
contain a dot, so a bare name such as
https://intranet/…is refused — with no fragment, wildcard or userinfo, at most 2048 characters; IP literals (v4 and v6),localhost,*.localhost,.local,.internal,.svcand.cluster.localare refused. At most 10 post-logout redirect URIs, matched character for character. - No registered back-channel URI means no back-channel logout, and no registered post-logout redirect URI means the person stops on the platform's "signed out" page instead of returning to your app. Back-channel delivery is best effort — retried, but losable across a platform restart — so never make it your only revocation signal, and no propagation time is promised.
- Registering a URI is not a promise that it will be called. The delivery client
judges the address at connection time and refuses a private one (private ranges,
loopback, cloud metadata
169.254.169.254, CGNAT100.64.0.0/10, IPv6 private and link-local, multicast, and the reserved and documentation ranges). An IPv4-mapped IPv6 address is judged as the IPv4 address it carries; the deprecated IPv4-compatible form (anything in::/96, such as::a00:1) is refused outright, whatever it carries. Registration checks the literal URI; delivery checks the address it resolves to now — so a URI that passed registration is still refused if its DNS later points somewhere private. If a name resolves to several addresses and any one of them is blocked, the whole name is refused, so do not give the endpoint a split-horizon record. Delivery is also at most once: if the platform restarts between ending the session and sending, the session stays ended and the notification is never retried. - Refusals of a logout registration are stable codes, never prose to match on:
too_many_urisandinvalid_uri(withfield, anindexforpostLogoutRedirectUris, and areasonout oftoo_long— 2048 bytes —unparsable,not_https,wildcard,userinfo,fragment,ip_literal,private_host,not_fully_qualified) on 400;client_not_foundandnot_foundon 404;temporarily_unavailableon 503. The first offending URI is reported, not all of them, and the checks run in a fixed order, so a URI breaking two rules reports the first one reached. - RP-initiated logout is bound to the browser. If the request does not come from the
browser that holds the session, the person sees a confirmation page first — an
id_token_hintcan be copied, so it alone must not sign anyone out. A server-side call to the logout endpoint therefore does not silently end a session. Thepost_logout_redirect_uriis checked before the binding, so an unregistered redirect is a 400 error page and the person is not signed out. - A first-party ID token is accepted as the hint, since the discovery document
advertises this endpoint. That path allows a redirect matching, exactly, the
redirect_urisof that client as registered on the token's own tenant — the platform never looks the client id up across tenants — or any https URL on that tenant's own domain, and shows the signed-out page otherwise. It does not end the first-party sign-in, which lives in each BFF's own cookie. The looser rule is first-party only: a third-party hint still accepts nothing but an exact value from its logout registration.
Errors
Errors are application/problem+json with a stable machine-readable error code, a
human message that may change wording at any time, and a requestId.
Every response — success or failure — carries x-request-id. Include it in any support
request; it is also the idempotency key the platform meters on.
The two codes worth internalising: 403 means no, retrying will not help. 503 means the platform cannot decide right now, retry with exponential backoff.
| Status | error codes |
|---|---|
| 401 | invalid_token |
| 403 | 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 |
| 404 | not_found |
| 409 | revision_conflict, already_exists, idempotency_key_reused, request_in_progress, order_not_cancellable, tag_writes_not_open, person_merged, tag_name_conflict |
| 413 | payload_too_large |
| 422 | quota_exceeded, schema_invalid, product_unavailable, tag_limit_reached, category_not_found |
| 428 | precondition_required |
| 429 | rate_limited |
| 503 | authorization_unavailable, token_verification_unavailable |
The 403 codes are the gateway's stable deny reasons. Two of them — tenant_mismatch
and no_relationship — come back as 404 on a person resource, so that the
difference between 403 and 404 is not itself a probe for whether a person exists.
forbidden is the catch-all for a deny reason this version of the gateway does not
recognise: still a denial, never a pass and never a retryable 503. What each code means
and how to fix it is in the API reference, generated from the contract.
Metadata
A small amount of structured data can be attached to a person, addressed by
(tenant, person, extension). The tenant comes from the token, never from a parameter.
Every write must state its precondition, with plain RFC 9110 semantics: create with
If-None-Match: *, update with If-Match: "<etag>". There is no unconditional
overwrite — neither header, or both, is 428 precondition_required. Every conflict
is 409, never 412: already_exists when you tried to create something that is there,
revision_conflict when the version moved under you. Both write nothing.
| Limit | Value | On exceed |
|---|---|---|
| 單筆 data 大小 | 16 KiB | 413 |
| 每 tenant 每 extension 筆數 | 50,000 | 422 quota_exceeded |
| 每 tenant extension 數 | 20 | 422 quota_exceeded |
| 分頁每頁筆數 | 預設 20,上限 100 | 422 |
Quota exhaustion never deletes data: writes are refused, reads, deletes and export stay available. Do not store photos, per-question event streams, unbounded lists, or anything that is treated as a permission, a balance, an entitlement or an identity binding.
Orders (preview, added 2026-10-17)
Three operations let a tenant's own back-office tool create an unpaid order for one of
its customers: POST /v1/orders, GET /v1/orders/{orderId} and
POST /v1/orders/{orderId}/cancel, under lightup.order.create, .read and .cancel.
They are preview, machine tokens only (a user token gets 403 profile_not_supported),
and the resource is the tenant, not the person.
Idempotency-Keyis required on create (1–200 visible ASCII characters). Replaying the same key with the same request returns the original order with 200; the same key with a different request is 409idempotency_key_reused.- Prices come only from the product catalogue. There is no price field to send; unknown
fields are 422
schema_invalid. customerPersonIdis apsn_TypeID. Use the value the platform gave you; if all you hold is this platform's legacy customer UUID (for example the customer id on an existing order), it is the same 128-bit value and converts losslessly under the TypeID specification (jetify-com/typeid,spec). Do not build it any other way.X-LightUp-Operatoris an annotation for audit only. It does not take part in authorization.
The Chinese page 訂單(預覽) has the full rules and the handling for each 409 and 422 code.
Tags and persons (preview, added 2026-10-19; writes preview since 2026-10-26)
Six read operations let a tenant's own back-office tool read the tenant's tags and
customers, all machine tokens only (a user token gets 403 profile_not_supported), with
the tenant as the resource:
lightup.tag.read(preview):GET /v1/tags/{tagId}/members(one page of the customers holding a tag; passnextback asafter),POST /v1/persons:tags(the tags of up to 100 customers),POST /v1/tags:lookupandPOST /v1/categories:lookup(ids by name; each answer isFOUND,NOT_FOUNDorAMBIGUOUS, and the platform never picks for you).lightup.person.resolve(preview):POST /v1/persons:resolvemaps up to 500 legacy customer ids to person ids (RESOLVED,NOT_FOUND,AMBIGUOUS,INVALID).lightup.line.target(preview):POST /v1/line-targetssays whether each of up to 100 customers can be reached on LINE. Only aDELIVERABLEanswer carrieslineUserId, which is the customer's LINE user id under the tenant's own LINE official account: it is meaningless with any other official account.
lightup.person.profile.read (preview, added 2026-10-25) covers
POST /v1/persons:profiles: a closed body {"ids": [...]} of 1–500 ids, each 1–128
characters, a bare legacy customer UUID or a psn_ person id, told apart exactly as
persons:resolve does. There is no listing form: name every customer you read. Each id
answers FOUND, NOT_FOUND, AMBIGUOUS or INVALID; only FOUND carries personId and
five fields that are always present and null when absent: givenName, familyName,
displayName, birthDate (YYYY-MM-DD) and gender (male, female, other or
unknown). A child created in the new system often has only displayName, so fall back to
it when both name parts are null. A value outside those rules is answered as null, and
no phone, email or address is ever returned.
Five write operations moved from planned to preview on 2026-10-26; until the release
that carries them is deployed, a call still answers 404 (the route is not mounted yet).
Do not start writing tag memberships before the tenant's identity cutover is complete:
until then every membership write answers 409 tag_writes_not_open, which is the
tenant's state, not a permission problem, so retrying, a new token or a new grant does not
change it. Creating a tag (POST /v1/tags) is not behind that gate.
lightup.tag.write covers PUT / DELETE /v1/persons/{personId}/tags/{tagId} and
POST /v1/tags/{tagId}/members:add / :remove; their Idempotency-Key must be a
(non-nil) UUID in the hyphenated 8-4-4-4-12 form (either hex case), unlike the order key. lightup.tag.define covers POST /v1/tags, which
answers 201 for a new tag and 200 with the existing tagId when the category already has
one of that name.
Request bodies are closed (an unknown field is 422 schema_invalid, and so is an unknown query
parameter on the members page); a malformed id in the path is 404. New codes: 409 tag_writes_not_open, person_merged, tag_name_conflict;
422 tag_limit_reached, category_not_found. "Grant everything" stores the catalogue as
it was at that moment, so a grant recorded before 2026-10-19 does not gain these
capabilities, and one recorded before 2026-10-26 does not gain the two writes. The Chinese page 標籤與顧客(預覽) has the full
rules.
LINE message groups (preview, added 2026-10-19)
lightup.line.message_group.read reads the tenant's LINE message groups (prepared sets of
LINE messages) so a tenant's own back-office tool can send them through the tenant's own
official account. Machine tokens only; the resource is the tenant.
GET /v1/line-message-groups?name=…takes exactly onenameand no other parameter (1–200 characters after trimming, else 422schema_invalid). It matches the trimmed name exactly, orders by id and returns at most 10 groups as{name, matched, truncated, items}. If you need exactly one group, use it only whenmatchedis 1 andtruncatedis false.GET /v1/line-message-groups/{groupId}returns one group. An id that is not 1–64[A-Za-z0-9_-]is 404 before authorization (ids migrated from the old system are kept, so they are not always UUIDs); a missing group or another tenant's is 404 too.- A group is
{id, name, updatedAt, messages}. Each message hastype(string or null) andcomplete, plustextfor text ororiginalContentId/previewImageIdfor image and video. Those are media ids, never URLs. Any other type is{type, complete: false}. Do not send a group that contains a message withcomplete: false.
No new error codes. The Chinese page LINE 訊息組(預覽) has the full rules.
Compatibility
/v1 in the path. Added fields do not bump the version — tolerate unknown fields.
Removing a field or changing its meaning bumps to /v2. Deprecations are announced at
least 90 days ahead, through the changelog on this site and in the offline bundle.
Offline bundle
The website and the versioned offline bundle are produced by the same build from the same
sources. The bundle carries the OpenAPI document, extracted JSON schemas, all guides,
runnable examples with a mock server, llms.txt / llms-full.txt for AI tooling, the
changelog, and a manifest.json with the contract version, source commit and a sha256 for
every file.
Registering an application
Everything below is done by the tenant administrator in the LightUp dashboard's integrations page, not by a support ticket: registering the app (for user sign-in, for machine-to-machine, or for both), editing its redirect, post-logout redirect and back-channel logout URIs, granting and revoking capabilities, and creating, rotating, disabling and re-enabling service accounts. You supply the values; the tenant administrator submits them. If the page is missing, that tenant has not been opened for third-party integration yet.
Support
Include the x-request-id, the timestamp, the operation, your client id, the status and
error code, and the contract version. Never include tokens, secrets or real customer
data. If a credential was exposed, ask for revocation first, then rotate.