Base URL
Authentication
Auth Agent uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) for secure authorization. All API endpoints require proper authentication as described in their respective documentation.Endpoint Categories
OAuth Endpoints
Standard OAuth 2.1 endpoints for authorization and token management
Agent Back-Channel
Agent-to-server communication endpoints for authentication flow
Discovery
OAuth server metadata and JWKS endpoints
OAuth Endpoints
Public endpoints implementing the OAuth 2.1 standard:/authorize
GET - Start OAuth authorization flow
/token
POST - Exchange authorization code or refresh token for access tokens
/userinfo
GET - Get user information (email only - no name or username)
/introspect
POST - Validate and inspect tokens
/revoke
POST - Revoke access or refresh tokens
Agent Back-Channel Endpoints
Endpoints used by agents to authenticate via back-channel:/api/agent/authenticate
POST - Authenticate agent and create authorization code
/api/check-status
GET - Poll for authorization status
Discovery Endpoints
OAuth server metadata and key information:/.well-known/oauth-authorization-server
GET - OAuth 2.0 server metadata
/.well-known/jwks.json
GET - JSON Web Key Set
Rate Limiting
Currently, Auth Agent does not implement rate limiting. This may change in future versions.Error Responses
All endpoints follow standard OAuth 2.0 error response format:Common Error Codes
| Code | Description |
|---|---|
invalid_request | The request is missing a required parameter or is malformed |
invalid_client | Client authentication failed |
invalid_grant | The authorization code or refresh token is invalid or expired |
unauthorized_client | The client is not authorized to use this grant type |
unsupported_grant_type | The grant type is not supported |
invalid_scope | The requested scope is invalid or unknown |
server_error | Internal server error occurred |
Security
PKCE Required
PKCE Required
All authorization flows must use PKCE (Proof Key for Code Exchange) with the S256 method. Plain code challenges are not supported.
HTTPS Required
HTTPS Required
All redirect URIs must use HTTPS, except for localhost development. HTTP is only allowed for localhost URLs.
Token Rotation
Token Rotation
Refresh tokens are automatically rotated on each use. When you use a refresh token to get new access tokens, the old refresh token is revoked and a new one is issued.
Secure Secrets
Secure Secrets
All secrets (agent secrets, client secrets) are hashed using bcrypt with 10 rounds before storage. Never share your secrets in client-side code.