Session Token Errors
If you encounter 401 Unauthorized errors related to "Invalid or Expired Session Token", this indicates either an expired cloud synchronization session or a desynchronized local proxy session token.
1Local Proxy Session Token Issues
The local background proxy daemon protects itself from unauthorized local programs using a pre-shared session token stored in the OS Keychain (X-AS-Session-Token).
Solution: Rotate the Session Token
You do not need to log out of your account. Simply rotate the local proxy session token:
agentsecrets proxy rotate-session
This command generates a new server-side session token, updates the running proxy daemon, and writes the new token directly to your secure OS Keychain.
2Cloud API Session Expiration
When you log in, the CLI stores a session token in the native OS Keychain to authenticate zero-knowledge synchronization requests against the cloud backend.
Automatic Token Refresh
In v3.1.0+, the CLI automatically refreshes your cloud session in the background using your secure Refresh Token during regular command invocations.
Manual Re-Authentication
If your session has expired after extended offline inactivity (or if the refresh token was revoked):
agentsecrets login
Note: You do not need to run agentsecrets logout before logging in. Logging in automatically replaces the expired session token in your OS Keychain.
3Clearing Stale Sessions (Optional)
If you need to completely clear your authenticated session state to switch accounts:
agentsecrets logout
This wipes session tokens from your local OS Keychain cleanly.