Tokens

Fruxon tokens are scoped bearer credentials for programmatic access. Use them for server-to-server agent execution, MCP clients, CI jobs, webhook delivery, and other non-browser callers.

Send every Fruxon token with the standard bearer header:

Authorization: Bearer <token>

Do not send Fruxon tokens in X-API-KEY. That legacy header is no longer accepted by the API. New docs and generated snippets should use Authorization: Bearer.

Token types

Type	Prefix	Owner	Best for
Personal access token	`fx_pat_...`	A human user	Local development, scripts owned by one person, temporary automation.
Service-account token	`fx_sat_...`	A service account principal	Production services, CI, webhooks, and workloads that should survive staff changes.

Personal access tokens and service-account tokens use the same scopes, headers, and request paths. The difference is the principal behind the credential: a personal token acts as its owning user, while a service-account token acts as a non-human workload identity. See Service Accounts when a token should belong to a workload instead of a person.

Create a personal token

Open Settings -> API Access -> Personal tokens -> Create token.

You choose a preset or pick scopes individually:

Presets are a least-privilege ladder — each rung adds to the one below:

Preset	Grants	When to use
Observer	Every `:read` scope, nothing else	Dashboards, exporters, audits, a read-only review pass
Operator	Run deployed agents and read traces — mutates nothing	A deployed bot that calls other agents; safe for unattended LLM agents
Developer	Author and validate agents, drafts, tools, and integrations, and run them — but can't deploy or reach outside the workspace	The recommended default for CLI / build workflows
Maintainer	Everything a developer can do, plus deploy revisions live and manage triggers	Trusted CI and operators who ship to production
Admin	Every scope, including the reach-scopes (send messages, fire triggers, rotate secrets), `keys:write`, and `workspace:write`	One-off ops; use sparingly

Presets are expanded into scope sets at mint time. The preset name itself is not persisted; only the resulting scope list is stored. The reach-scopes (participants:send, triggers:fire, secrets:write) are never bundled below Admin — add them à la carte on top of a lower preset when a workload genuinely needs them.

The token secret is shown once. Store it immediately in your secret manager. If you lose it, rotate or revoke and mint a new one.

Scope vocabulary

Scopes follow the pattern resource:action.

Resource	Actions
`agents`	`read`, `write`, `execute`, `test`
`revisions`	`read`, `write`, `deploy`
`integrations`	`read`, `write`
`tools`	`read`, `write`, `test`
`executions`	`read`
`traces`	`read`, `write`
`skills`	`read`, `write`
`llm_providers`	`read`, `write`, `test`
`datasets`	`read`, `write`
`assets`	`read`, `write`
`secrets`	`read`, `write`
`drafts`	`read`, `write`
`triggers`	`read`, `write`, `fire`
`participants`	`read`, `write`, `send`
`connectors`	`read`, `write`, `test`
`chat_users`	`read`, `write`
`keys`	`read`, `write`
`workspace`	`read`, `write`
`inbound`	`deliver`
`mcp`	`invoke`

Discover the live vocabulary programmatically through the Tokens API.

Use a token

Send the token as a bearer credential on any request — for example, executing an agent:

curl -X POST "https://api.fruxon.com/v1/tenants/{tenant}/agents/{agent}:execute" \
  -H "Authorization: Bearer $FRUXON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"topic": "the EU AI Act"}}'

To inspect the scopes on the token you're holding without revealing the secret, call GET tokens/current. The response includes the token's name, display prefix, scopes, expiry, and last-used timestamp — useful for SDKs and CI jobs that want to fail fast on a misprovisioned credential.

Rotate a token

Rotating mints a replacement token and revokes the old secret. By default the replacement inherits the original token's name, scopes, type, and expiry. You can also pass overrides to narrow scopes, rename the token, or set a new expiry during the same call — see POST tokens:rotate.

The old secret stops working as soon as rotation completes. Put the new value in your secret manager before you remove the old one from consumers.

Audit and activity

Every issuance, rotation, scope change, and revocation is recorded. View it from Settings -> API Access -> Personal tokens -> select a token -> Audit history, or fetch it through GET tokens/{token}/auditEvents.

Request activity is separate from lifecycle audit history. It is cursor-paginated because it can be high-volume, and is available through GET tokens/{token}/activity. Activity events include the endpoint called, status code, latency, actor, and request context.

MCP tokens

Each integration config that exposes MCP auto-mints a dedicated token scoped to mcp:invoke. You don't manage these by hand; they appear under the integration's MCP tab, with a Rotate action that issues a fresh value without disturbing the rest of your token inventory.

The MCP call URL and sandbox URL are shown in the same tab once the config has been persisted. See MCP for how to expose tools over MCP and point a client at the server.

Webhook and inbound delivery

Inbound webhook delivery endpoints are gated by the dedicated inbound:deliver scope. Use a separate token with only that scope for each delivery source so a leak cannot be replayed against the broader control plane.

Bearer auth is preferred. Some third-party webhook configurators can only send a static URL; those routes may carry the token in an apiKey query parameter or {apiKeyAuth} path segment. Treat URL-carried tokens as delivery-only credentials and rotate them if they appear in logs.

Endpoint reference

See the Tokens API for the full endpoint surface — list, mint, rotate, introspect, audit, and revoke.

CLI

The fruxon CLI still exposes token management under fruxon keys for compatibility. It covers read, revoke, delete, history, and scope discovery. Minting and rotation happen in the dashboard so the full secret is shown only in a human-authenticated browser session, not printed into an LLM agent or CI log.

See CLI -> Manage tokens for the full command surface.

Best practices

Use service accounts for workloads. A production service, webhook, scheduled job, and CI pipeline should not depend on a human user's token.
One token per consumer. A bot, a CI pipeline, and a notebook each get their own credential. Revoking one doesn't disturb the others.
Prefer presets, narrow when needed. Start with Operator for execution, Observer for dashboards, Developer for build workflows, then customize only when needed.
Set an expiry. Expired-but-rotatable beats long-lived-and-forgotten.
Treat fx_pat_* and fx_sat_* like passwords. Never commit, paste, or share them across environments.

Next steps

Service Accounts — workload identities and fx_sat_ tokens
CLI — read-and-revoke from the terminal
Security — auth, audit, and credential protection
Settings — where tokens are managed in the UI
API Reference — the full HTTP surface

Tokens

On this page