FOUNDATIONS

Authentication & tenants

A workspace header selects the tenant. A Bearer key authorizes the request.

Authorization: Bearer YOUR_API_KEY
X-Luma-Workspace-Host: acme.lumi-cx.com

Create a key in your workspace

Open Settings → Developer Options → API keys. Only the workspace owner or an explicitly authorized key manager can issue keys. Save the secret when it is displayed: it is stored hashed and cannot be retrieved later.

Grant only the permissions you need

Keys default to read-only. Write, delete and SOP approval are separate permissions. Webhook management requires explicit webhooks scopes; write/test also require ideas:read. Knowledge Bank, surveys and journeys reads include drafts. Survey results, publication and respondent links require additional explicit permissions. Contacts is not available in this release.

Key expiry is required (1–365 days; default 90). Rotation replaces the secret. Revocation blocks subsequent requests; an already-authorized request may finish first.

Opening from a workspace

The workspace name can travel in a link. Credentials never travel in URLs, cookies or browser storage. Use “Open docs with this key” in the workspace tester to explicitly transfer an entered key through a one-time, origin-checked in-memory handshake. The portal never transfers your login session.

Error responses

401: missing, expired, revoked or wrong-workspace key. 403: missing scope, unavailable module or suspended workspace. 404: unknown workspace, route or inaccessible record. 429: slow down and honor Retry-After.