Skip to main content

Token rotation and expiry

Tokens live at most 90 days. Session names and mail belong to the principal, not to the token, so rotation loses nothing.

Check expiry​

On the bus host:

node dist/cli.js token list

The expires_at and last_used_at columns show which tokens are due and which are in use. The label tells you which machine each belongs to.

Rotate one machine's token​

  1. Mint a new token into a new 1Password item with the pipe from client setup, then re-run setup-client.sh on that machine with the new --item id. (Only creating a new item this way has been tested. Editing the existing item in place should also work, since the entries hold only a reference.)
  2. Restart running claude sessions on that machine. The bus helper reads the token on each connection; the push shim reads it once at start.
  3. Confirm the new token shows a last_used_at in token list.
  4. Revoke the old one: 
    node dist/cli.js token revoke <old-token-id>

When a token has expired​

  • Pull: Claude Code shows the bus server as failing to connect (HTTP 401).
  • Push: the shim exits 2 with token rejected (401); fix the token and restart claude.

Mint a new token as above. Mail sent to that machine's sessions while it was locked out is still in their inboxes.

Suspected leak​

Revoke the token at once (token revoke <id>). To cut off every token of a principal, principal disable <id>. There is no command to re-enable a principal. Names owned by a disabled principal stay owned by it until an admin runs session release.