Skip to Content
APIAuthentication
last verified · 2026-07-16

Authentication

Every /api/v1/* request (and the /api/mcp transport) accepts exactly two credential types. The API tries a Bearer token first, then falls back to a signed-in browser session.

Bearer token (the way to call the API from code)

Send your token as a standard Authorization header:

Authorization: Bearer lm-<your-token>

This is the credential every script, CLI, or agent harness should use. It is tenant-scoped — it resolves to exactly one project’s data — and it works against both the REST endpoints under /api/v1/* and the token-authenticated API transport (MCP) at /api/mcp.

Getting a token

While signed in to lumis.work in a browser, request one:

GET/api/mcp/token

Mints (rotates) your project’s token and returns the plaintext value once. Requires a Clerk session cookie — this is a self-service action for a signed-in human, not something another Bearer token can call on your behalf. Calling it again invalidates the previous token, so treat rotation as intentional: every script or harness holding the old value needs the new one.

curl
curl https://lumis.work/api/mcp/token \
  -H "Cookie: __session=<your Clerk session cookie>"
TypeScript
const res = await fetch('https://lumis.work/api/mcp/token', {
  headers: { cookie: `__session=${sessionCookie}` },
});
const { mcpToken, setupCommand } = await res.json();
Python
import requests
 
res = requests.get(
    "https://lumis.work/api/mcp/token",
    cookies={"__session": session_cookie},
)
token = res.json()["mcpToken"]
{
  "mcpToken": "lm-3f9c2a1e...",
  "tenantId": "acme-co",
  "mcpServerUrl": "https://lumis.work/api/mcp",
  "setupCommand": "export LUMIS_MCP_TOKEN=lm-3f9c2a1e..."
}

If an administrator has revoked your key, this endpoint returns 403 instead of silently re-minting it — ask your admin to restore access rather than retrying.

The browser app itself authenticates with a Clerk session cookie (__session). This path exists so the web UI can call the same /api/v1/* routes it renders — it isn’t a mechanism external integrations should build against. If you’re writing a script, a CI job, or an agent integration, use a Bearer token.

Keep it secret

A Bearer token is a bare-secret credential — anyone holding it can act as your project for as long as it’s valid. Don’t commit it, don’t log it, and don’t paste it into a chat with an untrusted party. Rotate it (call the endpoint above again) the moment you suspect it leaked.

OverviewTickets