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