What an agent token is for

Agent tokens authenticate non-interactive callers (the citadel-cli, MCP clients, CI runners) the same way a signed-in user authenticates with a JWT. They carry the holder's permission grants minus any session-scoped step-up.

Issue a token

Settings → Access → New token. Pick:

Label. Where the token will live ("M2 laptop CLI", "GitHub Actions").
Expiry. 90 days is the v1 default; pick longer only if the consuming system can't rotate.

The plaintext token is shown once. Copy it into your password manager or environment file before navigating away. Citadel only stores the SHA-256 hash.

Use it with the CLI

citadel-cli auth login --token $CITADEL_AGENT_TOKEN

The CLI persists session state under ~/.config/citadel/. Subsequent commands authenticate automatically.

Use it with MCP

Set the token as the bearer credential against https://mcp.src.land/mcp in your MCP client config. Citadel accepts both agent tokens and Supabase OAuth-JWTs on the same endpoint.

Rotation

Issue a new token, ship it to the consumer, then revoke the old one. There is no in-place rotation, by design, since rotation typically pairs with credential cycling.

Revocation

Click Revoke in the tokens list. Revoke is immediate (no propagation delay); subsequent calls return 401.

Agent tokens