Authentication

All requests to the AgentSecrets API (except for user registration, login, and token refresh) must be authenticated. The API implements JSON Web Tokens (JWT) and static service keys to authorize clients.

Token Types

The backend supports three categories of tokens:

1User Session Tokens

Who uses it: Human developers via the CLI or web dashboard.
Format: Standard JWT containing the user's UUID, email, and permissions.
Lifecycle: Access token expires in 6 hours; Refresh token uses standard JWT refresh lifetimes.
Storage: Saved locally on the developer's machine inside the secure OS Keychain (with token.json kept empty of sensitive data).

2Agent Tokens

Who uses it: Credential proxies, MCP servers, or background runners.
Format: Cryptographically signed agent tokens representing a specific declared identity.
Lifecycle: Configurable lifecycle (e.g., 24 hours up to 30 days) and scope. Can be revoked at any time.

3Service Keys

Who uses it: Internal backend-to-backend resolver components.
Format: High-entropy static bearer keys configured in the environment (RESOLVER_SERVICE_KEY).

Including Tokens in Requests

To authenticate a request, include the token in the Authorization header as a Bearer token:

Authorization: Bearer <your_jwt_or_agent_token>

For internal resolver calls, the backend acceptsAuthorization: Bearer <resolver_service_key> or matches the service key against a custom internal header, falling back to User JWT authentication if service key validation is not enforced.

Expiry and Refresh Flow

To prevent developers from being logged out during long-running tasks or background syncing (such as the proxy daemon syncing audit logs to the cloud), the CLI API client implements an automatic retry mechanism.

401 Detection: If an API request to a private endpoint fails with a 401 Unauthorized status (indicating the Access Token has expired), the client pauses.
Dynamic Refresh: The client issues a POST request to /api/auth/refresh/ using the stored Refresh Token.
Save and Retry: If the refresh is successful, the new Access and Refresh tokens are persisted to the secure OS Keychain (leaving the local token.json file empty of secrets) and the failed request is re-built and executed exactly once with the new token.
Concurrency Protection: The refresh flow is locked using a mutex (refreshMu) to ensure that multiple parallel asynchronous requests do not cause a "refresh storm" by hitting the refresh endpoint concurrently.

Revocation

Tokens can be revoked in three ways:

Logout: Running agentsecrets logout calls the /api/auth/logout/ endpoint, blacklisting the active refresh token.
Agent Revocation: Through the workspaces dashboard or CLI:
```
agentsecrets agent token revoke <token_id>
```
Password Change: Changing your master password automatically invalidates all existing active user sessions.