Tokens & API keys¶

Lantern has two kinds of token, both presented to the server as Authorization: Bearer <token>:

Type	Prefix	Who it's for	Where you make it
Personal access token (PAT)	`lnt_pat_…`	You — for your AI tools (Claude, Cursor, Codex)	The Tokens page (`/tokens`) in the web UI
Service key	`ltr_key_…`	CI / automation callers	REST: `POST /api/v1/auth/keys`

For day-to-day use you want a PAT. The service-key REST flow is an advanced/automation path documented at the bottom.

Both token types are secrets — like SSH keys. Don't commit them, don't paste them in Slack / Telegram, don't share. Each is shown exactly once at creation; store it in your password manager immediately.

Personal access tokens (the `/tokens` page)¶

Once you've signed in, open /tokens. The page lists your existing tokens and lets you create, rotate, and revoke them. The raw token value is revealed once in a modal with a copy button — it is never written to browser storage, never logged, and never put in a URL. Copy it then; you cannot read it again.

Create a token¶

Go to /tokens.
Click Create, give it a name (e.g. claude-desktop), pick scopes, and an optional TTL.
Copy the revealed lnt_pat_… value into your password manager and into your AI tool's MCP config (see Connect your AI tool).

Scopes¶

Scope	What it allows
`read`	Search, fetch, graph navigation, context pack. No writes.
`write`	Above + Confluence / Jira writes (sections, comments, transitions, create).
`admin`	Above + user management, key issuance, audit-log access. Operators only.

Start with read. Add write only when you need the agent to update docs or transition issues. You cannot mint a token with more scope than your own account holds — a non-admin requesting admin is rejected with 403.

TTL¶

Pick how long the token lives: 1–365 days (default 90 — rotate quarterly). Operators can also issue never-expiring tokens for LAN-only use.

List / revoke / rotate¶

List — the page shows each token's name, scopes, prefix, expiry, and last-used time. The full value is never shown again, only the prefix.
Revoke — kills a token immediately. Lost a laptop or suspect a leak? Revoke first, ask questions later.
Rotate — issues a fresh secret for the same token and either revokes the old one at once (grace = 0) or keeps it alive for a short grace period so you can swap configs without an outage. Rotated tokens are tagged with a rotated badge.

Rotate every 90 days, or whenever a teammate leaves or a key may have leaked.

Service keys (REST, for automation)¶

Service keys (ltr_key_…) are for CI and automation callers, not interactive use. Creating one requires a session (or token) with the write scope.

Create¶

curl -s --cookie 'lantern_token=<your cookie>' \
  -X POST https://lantern.evgeniy.online/api/v1/auth/keys \
  -H 'Content-Type: application/json' \
  -d '{"name": "ci-runner", "scopes": ["read"], "ttl_days": 90}'

Response (the key is shown once):

{
  "id": "00000000-0000-0000-0000-000000000000",
  "key": "ltr_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "xxxxxxxx",
  "scopes": ["read"],
  "expires_at": "2026-01-01T00:00:00+00:00"
}

key_prefix is the first 8 characters of the random part — used only to identify the key in listings, never the full secret.

List¶

curl -s --cookie 'lantern_token=<your cookie>' \
  https://lantern.evgeniy.online/api/v1/auth/keys

Returns an array with each key's key_prefix, scopes, name, expires_at, last_used_at, and created_at. The full key is never returned again.

Revoke¶

curl -s --cookie 'lantern_token=<your cookie>' \
  -X DELETE https://lantern.evgeniy.online/api/v1/auth/keys/<key-id>

Revocation takes effect on the next request from the client (within ~1 minute). Revoking also requires the write scope.

Token hygiene¶

Never post a token in Slack, Telegram, GitHub/GitLab issues, or commits.
Never commit a token to a repo — the lantern-mcp shim reads it from an environment variable; use ${LANTERN_BEARER} placeholders in JSON configs (see Connect your AI tool).
Lost / leaked → revoke first, ask questions later.
Store it in your password manager as a concealed field.

Troubleshooting¶

Symptom	Cause / fix
`401 invalid token`	Token revoked, expired, or copied wrong. Make a new one.
`403 insufficient scope`	Token has `read` but the action needs `write`. Mint a token with `write`.
`403 requested scopes exceed caller entitlement`	You asked for more scope than your account has (e.g. `admin`). Ask an operator.
`404 token not found` on revoke	Already revoked, or wrong id.
`422 ttl_days out of range`	Must be 1–365 (default 90 if omitted).