Get started

Authentication & API keys

Bearer API keys for live and test mode, scopes, rotation, and who can create them. API access is a Pro feature.

Send the key in the Authorization header on every request. Keys never go in query strings.

HTTP

GET /v1/me HTTP/1.1
Host: api.light-ai.app
Authorization: Bearer lai_live_…

Who has access#

API access is included on Pro (Pro, Enterprise and Pro trials). Free and Plus have no API access: no keys, no test mode, no webhooks and no inbound sources.

Off-Season keeps API reads and new leads (POST /v1/leads, inbound sources) when the home plan is Pro or Enterprise; every other write answers 403 organization_off_season until the owner resumes the plan.
A paused organization is read-only: writes answer 403 organization_paused and inbound leads are held until it resumes.
A downgrade below Pro suspends (never deletes) every key, inbound source, webhook endpoint and partner grant, right after an organization.entitlement_changed event. An upgrade back to Pro restores them.
There is nothing to request: every Pro and Enterprise organization can create keys in Settings → Developers.

Key types#

Prefix	What it is	Created in
`lai_live_…`	Live organization key: real data.	Settings → Developers (owner)
`lai_test_…`	Test organization key: isolated test objects, no e-mails, no credits. See Test mode.	Settings → Developers (owner)
`lai_live_…` / `lai_test_…` of a partner	Partner key: acts for connected contractors with `Light-AI-Organization: org_…`. See Partners.	Partner console (second factor required)
`lai_whin_…`	Inbound source secret: can only send leads in. See Inbound leads.	Settings → Developers → Inbound
`whsec_…`	Webhook signing secret (not an API key).	Returned when an endpoint is created

Keys carry a checksum, so a mistyped key fails fast with 401 invalid_api_key, and secret scanners can recognize a leaked one.

Creating keys#

The owner (or an admin the owner allowed) creates and rolls keys after a recent sign-in (step-up, with MFA when enabled). Revoking needs no re-sign-in.
Choose scopes (presets: Integration partner, Lead intake only, Read only), an expiry (30 days, 90 days, 1 year or never; partner keys 30–90 days) and optionally up to 20 allowed IP ranges.
The key is shown once. Light AI stores only a hash and the last four characters.
At most 25 active keys per organization. Owners get an e-mail for every new key.

Scopes#

A key can do only what its scopes allow (for partner keys: key ∩ grant ∩ plan). GET /v1/me lists the effective scopes. A missing scope answers 403 insufficient_scope.

Scope	Allows
`leads:read`	Read leads and touches (names, e-mails, phones, addresses).
`leads:write`	Create and update leads. Without `leads:read` every answer is a receipt.
`clients:read` / `clients:write`	Read clients and properties / create, update and add properties.
`projects:read` / `projects:write`	Read projects and pipeline totals / move a project between stages.
`quotes:read`	Read published quotes, line items, totals, assets and timelines. Internal team comments and review notes on a quote are never returned by the API, MCP tools or webhooks.
`quotes:write`	Record approvals and declines made outside Light AI.
`quotes:share_link`	Opt-in. Receive the homeowner quote link (`customer_url`). Anyone holding it can view and approve the quote.
`quotes:asset_links`	Opt-in. Receive long-lived image links (up to 30 days).
`mockups:read` / `mockups:write`	Read generations / generate mockups with the contractor's credits. `mockups:write` is never in a preset.
`forms:read`	Read website request forms, their install snippets, settings and this month's preview use. See Website request forms.
`forms:write`	Opt-in. Pause, resume and adjust a website request form, including its instant preview spending. Owners are e-mailed when the websites change or previews are turned on.
`webhooks:manage`	Opt-in. Create and manage webhook endpoints through the API. Owners are e-mailed for each one.
`events:read`	Read the events feed.

Rotation#

Roll a key to get a new secret while the old one keeps working for a grace period you choose (immediately, 1 hour, 24 hours or 7 days). Expiring keys trigger api_key.expiring 14 and 3 days ahead. Revoked, expired and suspended keys answer 401 api_key_revoked, api_key_expired or api_key_suspended.

Headers#

Header	Use
`Authorization`	`Bearer <key>`. Required on every route except `/v1/status`, the inbound receivers (which take a source secret) and image links (`/a/…`).
`Light-AI-Organization`	Partner keys: the connected organization (`org_…`) to act for.
`Light-AI-Version`	Pin an API version (default: the key's version, `2026-11-01`).
`Idempotency-Key`	Safe retries for writes. See Idempotency.
`Request-Id` (response)	Unique per request. Include it when you contact support.