Skip to content

Authentication

Customer.lite takes two credentials: API keys, for your application and your AI assistant, and dashboard sessions, for people signed in to the dashboard. The API reference says which each action takes, under “Caller”.

An API key belongs to one project and acts only on it. Send it as a Bearer token, on REST and on MCP alike:

Authorization: Bearer cl_sk_...
  • Format. A secret key starts with cl_sk_. The prefix lets secret scanners recognise a leaked key.
  • Shown once. The key is stored hashed. Its plaintext is in the response that creates it and nowhere else; every later response shows only its prefix and last four characters.
  • Permissions. A secret key can call every project action: customers, events, workflows, messages, and metrics, including workflows.activate. It cannot call the actions that manage workspaces, members, projects, or keys; those answer forbidden to a key.
  • Managing keys. A workspace admin creates, lists, and revokes keys with apiKeys.create, apiKeys.list, and apiKeys.revoke, from a signed-in session. The dashboard does the same under Settings › API keys (Quickstart). A revoked key answers unauthorized from the next request on.
  • Keeping it secret. Keep keys in environment variables or a secret store, never in code you commit or in a page a browser loads. Revoke a key you suspect has leaked and create a new one.

Restricted keys, publishable keys for the browser, key expiry, and rotation are planned.

People sign in to the dashboard with a 6-digit code sent by email, valid for 5 minutes, or with Google where the installation has it set up. The session is a cookie that lasts 7 days, renewed while the dashboard is in use.

A session can call the REST API too, and is the only credential for the actions that manage workspaces, members, projects, and API keys. It acts with the person’s role in each workspace (Workspaces and projects), and names what it acts on in a header:

Header For
Customer-Lite-Workspace: <workspace-id> Actions on a workspace: its members and projects.
Customer-Lite-Project: <project-id> Actions on a project: customers, events, workflows, messages, and API keys.

A session’s writes must come from the dashboard’s own origin, with a JSON body; others answer forbidden or unsupported_media_type. /mcp never accepts a session.

The MCP endpoint is <app-origin>/mcp, over Streamable HTTP. It takes a project API key as a Bearer token; see the Quickstart for Claude Code. A request without a valid key answers HTTP 401 with WWW-Authenticate: Bearer realm="customer-lite" (and error="invalid_token" when a key was sent but is not valid), before any tool runs.

Connecting by OAuth instead of a key, from Claude Code, claude.ai, and ChatGPT, is planned. Each connection would act as the person who consented, on one project, and could be revoked from the dashboard.