Troubleshooting Local Proxy Session Token Errors
If you receive 401 Unauthorized responses from the local proxy engine at http://localhost:8765/proxy or endpoints like /approve, /sync, or /rotate-session, your client is failing pre-shared session token validation.
Understanding Local Proxy Sessions
To prevent unauthorized scripts, browser tabs, or process-escaped programs on your host machine from accessing the local credential proxy, the AgentSecrets daemon gates access using a pre-shared session token.
- Lifecycle: A new session token is generated every time the proxy daemon starts (via
agentsecrets proxy startor transient execution). - Storage: The session token is stored securely in the native OS Keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). No plaintext token files exist on disk.
- Auto-Injection: The
agentsecretsCLI client and built-in MCP server automatically retrieve this token and inject it via theX-AS-Session-TokenHTTP header, making proxy operations completely seamless.
Diagnose and Fix
If you are using third-party clients, custom libraries, or experiencing connectivity issues, follow these steps to resolve token mismatch errors:
1Restart the Proxy Daemon
Restarting the daemon clears out stale processes and writes a fresh, valid session token to the secure local keychain. Run:
agentsecrets proxy stop agentsecrets proxy start
2Verify Client-Side Injection
If you are calling the proxy from custom HTTP scripts (e.g., in Node.js or Python) rather than the CLI client, you must read the pre-shared key from the OS Keychain and set it in your headers.
- Header Name:
X-AS-Session-Token - Command to Read: Use the CLI to safely print the active token:
(Note: This rotates the token and returns the active string, which you can load into your custom client context.)agentsecrets proxy rotate-session
3Check OS Keychain Availability
If the OS Keychain is locked or inaccessible (e.g. running in a headless SSH session without a configured D-Bus), the proxy cannot retrieve the session token.
- Verify your keychain status by running:
agentsecrets status - If running on headless Linux, ensure
dbus-run-sessionis configured or thatkeychain-authfallback files are writable.