Authentication
Scoped bearer tokens, minted per workspace — a token's authority is exactly its scopes, nothing more.
Minting a token
Settings → Workspace → API tokens (requires the workspace:manage permission, i.e. a workspace admin). Choose a name, the scopes, and an optional expiry. The raw token — grt_ + 40 hex characters — is shown once; only its hash is stored.
curl -s "$BASE/api/workflows" -H "Authorization: Bearer grt_xxxxxxxx…"Tokens are workspace-scoped: every call operates in the workspace the token was minted in. Machine calls skip CSRF entirely (no cookies involved).
Scopes
A token holds exactly the scopes granted at mint — never its creator's live role. Reads are enforced as strictly as writes.
| Scope | Grants |
|---|---|
workflow:read | List/read workflows, versions, exports, validation. |
workflow:write | Create, update, import, duplicate, folders/tags. |
workflow:delete | Delete workflows. |
workflow:publish | Publish and unpublish. |
workflow:run | Trigger runs, test steps, arm test listeners. |
connection:read | Connection metadata (never credential values). |
connection:write | Create/update/test/replace connections. |
connection:delete | Delete connections. |
run:read | Runs, step data, live streams, stats. |
run:manage | Cancel and delete runs. |
Deliberately not grantable to tokens: workspace:manage and org:manage. A leaked token can never escalate into tenancy management, mint further tokens, or read Keel conversations.
Failure semantics
| Status | Meaning |
|---|---|
401 UNAUTHORIZED | Missing, malformed, expired or revoked credential. A token pasted without the Bearer prefix gets a message saying exactly that. |
403 FORBIDDEN | Authenticated, but the token lacks the scope. The message names the missing permission. |
404 NOT_FOUND | Also the answer for resources in other tenants — existence is never disclosed across workspace boundaries. |
Revoke tokens from the same settings page; revocation is immediate.