Ingest keys and API keys

Logthread has two kinds of key. An ingest key sends data in. An API key reads data out, for AI agents and tools that connect through MCP. They are separate on purpose, and neither can do the other's job.

What is the difference between an ingest key and an API key?#

An ingest key sent to the MCP endpoint, or an API key sent to the ingest endpoint, is rejected.

Create an ingest key#

Open Keys in the sidebar (under Developers) and stay on the Ingest keys tab, choose Create ingest key, name it after the service or environment, and copy the key. It is shown once; only a digest is stored. Give each service or environment its own key so you can revoke one without touching the others.

Create an API key#

Open Keys, switch to the API keys tab (admins and owners; the tab is hidden for other roles), choose Create API key, and fill in:

• Key name, for example claude-code-pritam.
• Access: Read (logs, traces, metrics, patterns, alerts, annotations), plus optionally Run SQL (read-only SQL for the agent), Create annotations (the annotate scope), and the setup scopes: Set up alerts (alerts), Build dashboards (dashboards), Set up pipelines (pipelines), Manage collector configs (fleet) and Add sources (sources).
• Expires: Never, 30 days, 90 days or 1 year.

Copy the key; it is shown once. Treat it like a password because it reads your workspace data. To connect an agent, follow AI agents (MCP).

The annotate scope#

This scope also reports changes: deploys, config changes and flags, from CI.

annotate lets the key create chart annotations with POST /api/annotations or the MCP tool create_annotation, for example from a CI/CD pipeline that marks each release. It grants nothing else that writes: the key still cannot send logs, delete annotations or change settings. Any API key, with any scope, can list annotations. Give a pipeline its own key with only annotate, and keep it in your CI secret store.

The alerts scope#

alerts lets the key create alert rules with POST /api/alerts/rules (and preview them with POST /api/alerts/rules/preview), or with the MCP tool create_alert_rule. Use it to keep alert rules in code next to the service they watch; rules it creates over HTTP show no author and are audited as made by the key. Through MCP the same scope also lets an agent update rules (enable, mute, attach channels) and add and test channels, acting as the key's creator (below).

The setup scopes#

alerts, dashboards, pipelines, fleet and sources let an AI agent set Logthread up: alert rules and channels, dashboards (panels and variables) and saved searches, pipelines (created or edited, previewed on real records and activated only when confirmed), collector configs and their rollout, ingest keys and LiveKit. The agent acts as the person who created the key, within that person's current role: an admin's key can create pipelines, and stops being able to once that person is a member. A key belongs to its creator's membership: when that person is removed from the workspace, leaves it, or is deactivated through SCIM, the API keys they created are revoked (each revocation is in the audit log), and a key whose creator is no longer a member is refused for reads too. Nothing is ever deleted through these scopes, and each change is in the audit log under the creator's name with via: mcp.

What an API key can call over HTTP#

An API key is for tools, so almost everything it can do goes through the MCP endpoint. Only a few HTTP routes take it directly. Send it as Authorization: Bearer ltk_... or, behind a proxy that strips that header, as X-Logthread-Key: ltk_....

Every other /api/... route (Explore queries such as /api/explore/query, threads, dashboards, SQL console, usage, team) is the web app's own API: it needs a signed-in browser session and rejects API keys with 401. To read logs from a script, call the MCP server (search_logs, count_logs, run_sql) or export from the app; the full tool list is on the MCP page.

Revoke a key#

Open Keys, pick the Ingest keys or API keys tab, choose Revoke on the key and confirm. Revoking cannot be undone.

• A revoked ingest key stops ingesting within 60 seconds.
• A revoked API key loses access immediately on the server that handles the change and within 60 seconds everywhere.
• A refused revoked, expired or orphaned API key leaves an api_key.auth_failed event in the audit log (at most one per key every 10 minutes).

Every key change is recorded in the Audit log.

How do I rotate a key?#

There is no in-place rotation, so rotate in three steps with no gap:

1. Create a new key with a new name.
2. Deploy the new key to the service or agent.
3. Check that data still arrives, then revoke the old key.

I get 401 or 403 when I send data#

The key is wrong, revoked or an API key was used where an ingest key is needed. Check that the header is Authorization: Bearer <ingest key> (or X-Logthread-Key: <ingest key>), that no environment variable was left unexpanded, and that the key is still listed under Ingest keys. Create a new key if in doubt.

Next: send data with your new key.