Admin token rotation

PYLON_ADMIN_TOKEN authenticates every privileged route:

• /api/auth/session POST in non-dev
• /api/auth/upgrade in non-dev
• /api/admin/users/:id/export (GDPR export)
• /api/admin/users/:id/purge (GDPR delete)
• /api/sync/push from admin contexts
• Jobs / workflows / scheduler control planes
• /studio in non-dev

Treat it like an SSH key: minimum 32 bytes of randomness, never in git, rotate on any suspicion of compromise.

​

Without downtime (two-token rotation)

The server only reads PYLON_ADMIN_TOKEN at startup. Rotation requires a restart. To do it without dropping traffic:

1. Prepare. Generate the new token:
   openssl rand -hex 32 > /etc/pylon/admin_token.new
   
2. Deploy side-by-side. Start a new instance with the new token, let the load balancer health-check promote it, stop routing traffic to the old one, and let your load balancer’s connection drain finish so mid-request admin calls complete before you SIGTERM it. (SIGTERM itself is not graceful — see Deploy → Shutdown and rolling deploys — so the drain has to happen at the load balancer.)
3. Update clients. Any automation (CI, runbooks, cron, admin UIs) that hardcodes the old token must update. Grep for the old token prefix in Vault, 1Password, GitHub Actions secrets, Cloudflare environment, etc. before deleting the value.
4. Verify + scrub. Hit one admin endpoint with the new token; if it works, delete the old one from your secret store.

​

Emergency (suspected compromise)

1. Generate a new token — skip no-downtime, it’s not worth the risk:
   openssl rand -hex 32 > /etc/pylon/admin_token.new
   
2. Revoke every active session and force re-login. There is no global session-purge endpoint — invalidate all sessions by clearing the session DB and restarting. Every user signs back in on their next request (sessions are recoverable; only the login is lost):
   systemctl stop pylon
   rm /var/lib/pylon/sessions.db*
   systemctl start pylon
   
3. Rotate OAuth secrets too — same blast radius if the admin account was used to configure them.
4. Audit audit_log for the period the old token was valid. The audit_log plugin records who did what and when.
5. File an incident report per SECURITY.md.

​

On Pylon Cloud

Admin tokens are scoped per-workspace and managed via the dashboard. Rotation is a one-click operation with no downtime — Cloud handles the side-by-side restart for you. Old tokens stop working immediately on rotation.

​

What NOT to do

• Don’t use the admin token as a session token. Admin is not “a user”, it’s a break-glass credential.
• Don’t commit the token to git, even in a test fixture. The pre-commit hook rejects 32+ hex strings in tracked files.
• Don’t pass it as a URL query parameter. Authorization: Bearer only. URL params leak into proxy logs and browser history.
• Don’t reuse the token across environments. Staging ≠ prod.

​

Rotation cadence

Set a calendar reminder. Add it to your runbook.