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

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 with 403 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 answer 409 tag_writes_not_open until 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.tech for the API, developers.lightup.tech for 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.

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

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.

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.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.

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.