API Overview

Complete Auth Agent API reference

Base URL

https://api.auth-agent.com

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:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: client_id"
}

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

All authorization flows must use PKCE (Proof Key for Code Exchange) with the S256 method. Plain code challenges are not supported.

HTTPS Required

All redirect URIs must use HTTPS, except for localhost development. HTTP is only allowed for localhost URLs.

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

All secrets (agent secrets, client secrets) are hashed using bcrypt with 10 rounds before storage. Never share your secrets in client-side code.

SDKs and Libraries

Python

pip install auth-agent-tools

JavaScript/TypeScript

NPM package coming soon

Need Help?

Quickstart Guide

Get started in minutes

Integration Scenarios

Choose the right integration pattern

GitHub

View source code and contribute

Report Issues

Found a bug? Let us know