API ReferenceTalon Studio v1.0.2-beta

Authentication

Every request carries a scoped bearer token. Create one in Settings → API, send it in the Authorization header, and it acts with least privilege.

Bearer tokens

Authenticate with a token in the Authorization header. The scheme must be Bearer (case-insensitive); the API accepts nothing else. Talon tokens are prefixed tlk_ so secret scanners can spot a leak, stored only as a SHA-256 hash, and shown in full exactly once, at creation.

Authorization header

Authorization: Bearer tlk_<your-token-secret>

Personal (user) tokens act as you: their scopes are re-intersected with your live org role on every request, so demoting or disabling the owner shrinks the token's power immediately.

Service tokens are org-wide credentials (admin-only to create) that survive staff changes — their granted scopes stand on their own.

A token is org-scoped or bound to a single workspace. Passing a workspaceId that doesn't match a workspace-bound token's own workspace returns 403; 404 is reserved for a workspace that can't be found or reached.

A personal token's workspace reach is floored per scope: read scopes require the owner to hold at least viewer on that workspace, write scopes at least engineer — checked live against the owner's actual membership (direct, through a team, or as an org admin), never a token-supplied claim. Service tokens reach every workspace in the org.

The secret is tlk_ followed by 32 random bytes in base64url — 47 characters, about 256 bits of entropy. The app only ever shows its first 12 characters after creation. Lookups are by hash, with a constant-time compare.

Personal tokens die with their owner

Disabling a user immediately turns every personal token they created into a 401 — the owner's status and role are re-checked on each request, and deleting the user has the same effect. For unattended automation that must survive offboarding, have an admin create a service token, whose granted scopes stand on their own.

Creating a token

Create and revoke tokens under Settings → API, on the Auth tab (/settings/api), with Create token. Admins, engineers and analysts can create and revoke tokens; readonly users can't.

Name

Required, up to 120 characters, unique within the org. A name stays taken after its token is revoked — reusing it fails with 409.

Description

Optional, up to 500 characters.

Kind

Personal (acts as you) or Service (org-wide). Only admins can create service tokens.

Routing

Organisation (all workspaces) or One workspace. Non-admins can only bind a token to a workspace they can reach themselves; admins can bind to any workspace in the org. Deleting the workspace deletes its bound tokens.

Scopes

At least one. You can only grant a scope your own role could perform — see Scopes below. The form marks write scopes; on the Community Edition, creating a token with one is refused.

IP allowlist

Optional, up to 50 exact IP addresses, separated by commas or spaces. No CIDR ranges — an address must match exactly. Requires TALON_TRUST_PROXY=true on the server: without a declared trusted reverse proxy the client IP can't be trusted, so the server fails closed and rejects an allowlisted token with 403.

Expiry

Optional date. An expired token gets 401. Leave it empty for a token that never expires, and rotate it anyway.

Copy the secret when it's shown — it isn't recoverable. Revocation takes effect on the next request. The token list shows each token's name and kind, its prefix, routing, scopes, when it was last used, and its status.

Community Edition and Enterprise

The Community Edition — an instance on a Community key — gets the whole read API. Writes are held back for Enterprise, which is in development and not on sale.

Community Edition

Tokens may hold only read scopes, and the org may have at most 2 active tokens — counted across every user, not per user. Expired tokens still count until you revoke them; revoked ones don't. A third token, or any write scope, is refused when you try to create it.

Enterprise

Unlocks the seven non-read scopes (detections:propose, alerts:write, cases:write, kanban:write, search:execute, audit:read, users:read), the MCP server, and removes the token cap.

audit:read and users:read sound like reads, but they need the administer capability, so they count as write scopes and are unavailable on the Community Edition.

When a key lapses

The licence is re-checked on every write-scoped request, not only when the token was created. If an Enterprise key expires or is revoked, the instance returns to the Community Edition: read calls keep working, write-scoped calls get 403 with Write API scopes require an Enterprise license. Community tokens are read-only., and the MCP server refuses every call. Tokens already over the 2-token cap keep working, but no new token can be created while two or more are active. If the stored key stops verifying, or there is none, the instance is unlicensed and every call gets 403 licence_required until an admin pastes a key — see Errors.

Scopes

Each endpoint requires one scope. A role can grant a scope when it has the capability behind it: view (every role), propose and operate (admin, engineer, analyst), administer (admin only).

Scope	Endpoints	Granted by
me:read	GET /me	Any role
workspaces:read	GET /workspaces, GET /workspaces/{id}	Any role
detections:read	GET /detections, GET /detections/{id}	Any role
coverage:read	GET /coverage, /coverage/gaps, /coverage/navigator-layer, /adversaries, /adversaries/compare, /mitre/techniques/{techniqueId}	Any role
alerts:read	GET /alerts	Any role
cases:read	GET /cases, GET /cases/{id}	Any role
change_requests:read	GET /change-requests	Any role
standards:read	GET /standards	Any role
threat_feeds:read	GET /threat-feeds	Any role
deployments:read	GET /deployment-targets, GET /deployments	Any role
integrations:read	GET /integrations	Any role
kanban:read	GET /kanban/cards	Any role
agents:read	GET /agent-runs, GET /agent-runs/{id}	Any role
notifications:read	GET /notifications (org-scoped token)	Any role
license:read	GET /license (org-scoped token)	Any role
sourcetypes:read	GET /sourcetypes	Any role
blueprints:read	GET /blueprints, GET /blueprints/{id}	Any role
validate:read	GET /validate/summary	Any role
search:read	GET /search/sources	Any role
detections:propose	POST /detections, PATCH /detections/{id} — personal tokens only · Enterprise	Admin, engineer, analyst
alerts:write	PATCH /alerts/{id} · Enterprise	Admin, engineer, analyst
cases:write	POST /cases · Enterprise	Admin, engineer, analyst
kanban:write	POST /kanban/cards · Enterprise	Admin, engineer, analyst
search:execute	POST /search · Enterprise	Admin, engineer, analyst
audit:read	GET /audit-logs (org-scoped token) · Enterprise	Admin
users:read	GET /users (org-scoped token) · Enterprise	Admin

The org-wide endpoints — /audit-logs, /users, /notifications and /license — refuse a workspace-bound token with 403, because their data isn't partitioned by workspace.

Service tokens can't propose detections

POST /detections and PATCH /detections/{id} stage a change request that needs a human author, so they only work with a personal token — a service token holding detections:propose is still refused with a 403. For unattended proposal pipelines, create a personal token from a dedicated engineer account instead.

Example request

Confirm a token's identity and scopes with a call to /me:

curl

curl -H "Authorization: Bearer tlk_…" \

  https://<your-instance>/api/v1/me

200 OK

{

  "token": { "id": "…", "kind": "user", "scopes": ["detections:read"] },

  "orgId": "…",

  "workspaceId": null,

  "userId": "…"

}

Tip

Start every integration with GET /me — it tells you the token's kind, its effective scopes, and whether it's org- or workspace-scoped, so you can fail fast with a clear message instead of hitting a 403 deep in a workflow. It needs the me:read scope, so include that in every token.