Create scoped tokens for the /api/v1 REST API and the MCP server — hashed at rest, shown once, and bound by your permissions.
What it is
Tokens authenticate programmatic access to the /api/v1 REST API — the same data as the UI, exposed as predictable endpoints — and to Talon's own MCP server at /api/v1/mcp. Tokens are prefixed tlk_, stored only as a SHA-256 hash, and shown in full exactly once, at creation.
Settings → API (/settings/api) has two tabs: API, a reference of every endpoint built from the OpenAPI spec, and Auth, which holds the MCP server URL and the token list. Anyone signed in can open it; creating or revoking a token needs a role that can edit (analyst or above), and a Service token needs an admin.
How it works
Authenticate with a bearer header:
curl
curl -H "Authorization: Bearer tlk_…" \
https://<your-instance>/api/v1/detections
There are 26 scopes. Each needs a capability to grant — a token can never carry a scope its creator's role lacks:
alerts:write (triage and close alerts) · cases:write (promote and triage SOC cases) · kanban:write (create workboard cards) · search:execute (run a federated log search)
edit
detections:propose (propose a detection or an edit as a draft change request)
admin
audit:read (read the org audit log) · users:read (read the member roster)
Personal and Service. A Personal token acts as its creator: its scopes are re-intersected with the creator's current role on every request, and disabling the creator makes it fail with 401. A Service token is an org-wide credential that stands on its granted scopes; only admins can create one.
Routing. A token reaches the whole organisation or is locked to one workspace. A non-admin can only lock a token to a workspace they belong to.
IP allowlist. Optional, exact addresses only (no CIDR ranges). It is enforced only when TALON_TRUST_PROXY=true; without a trusted proxy an allowlisted token is refused rather than trusting a spoofable header.
Rate limits. 120 requests a minute per token (PUBLIC_API_RATE_LIMIT) and a 600-a-minute per-IP backstop checked before the token is looked up (PUBLIC_API_IP_RATE_LIMIT).
Propose-only writes.POST /api/v1/detections and PATCH /api/v1/detections/{id} stage a draft change request for human review; neither writes to git or deploys.
A token secret is 32 random bytes (base64url, about 256 bits of entropy) after the tlk_ prefix. Only its first 12 characters are kept afterwards, to show a masked prefix in the list.
Setup
1
Open Settings → API, switch to the Auth tab and click Create token.
2
Give it a Name (unique in the organisation) and an optional description, choose Personal or Service, choose Organisation or One workspace, and select the scopes. Write scopes are marked with a dot.
3
Optionally set an expiry date and an IP allowlist. An expired token is rejected on use even if it was never revoked.
4
Copy the token now — it's shown once. Revoke it from the list at any time; revocation takes effect on the next request.
Settings → API → Auth
The Create API token dialog — choose Personal or Service, Organisation or One workspace, select scopes, then copy the tlk_ secret immediately: it is shown only once.
Community Edition limits
On the Community Edition only the view scopes can be granted, and an organisation can hold 2 active tokens in total (not two per user). A revoked token frees its place; an expired one keeps it until you revoke it. The operate, edit and admin scopes — including audit:read and users:read — and more tokens come with Enterprise, which is in development. If a key lapses, a token's operate, edit and admin scopes stop working on the next request; its view scopes carry on.
Usage
Common /api/v1 endpoints. The API tab and the API reference cover the rest, and the spec is at /api/v1/openapi.json:
GET /me · /workspaces
Token identity, effective scopes, and the workspaces it can reach.
GET /detections · /detections/{id}
List and read detections (paginated).
POST /detections · PATCH /detections/{id}
Propose a detection or an edit — stages a draft change request.
GET /coverage · /alerts · PATCH /alerts/{id}
Read coverage and alert candidates; dismiss an alert.
GET /audit-logs
The org audit trail, newest first (audit:read, organisation-wide tokens only).
Proposing needs a Personal token
Proposing a detection or an edit requires a Personal token — a change request needs a human author, so a Service token is refused even when it holds detections:propose. For an unattended proposal pipeline, mint the token from a dedicated engineer account.