API Overview

Complete API reference for Auth-Agent OAuth 2.1 server

Base URL

Production: https://api.auth-agent.com
Local Dev:  http://localhost:8787

Authentication

Most endpoints require authentication via Bearer token:

Authorization: Bearer <access_token>

Endpoints by Category

OAuth 2.1 Endpoints

Standard OAuth 2.1 and OpenID Connect endpoints

Agent Management

Register and manage AI agents

Token Operations

Token exchange, refresh, and introspection

User Information

Retrieve authenticated user/agent information

OAuth 2.1 Endpoints

Endpoint	Method	Authentication	Description
/oauth2/authorize	GET	None	Start OAuth flow
/oauth2/token	POST	PKCE/Refresh Token	Exchange code or refresh tokens
/oauth2/userinfo	GET	Bearer Token	Get user information
/.well-known/openid-configuration	GET	None	OIDC discovery

Agent Endpoints

Endpoint	Method	Authentication	Description
/api/register-agent	POST	None	Register new agent
/api/agent-auth	POST	Agent Credentials	Authenticate agent
/api/agents/profile	GET	Bearer Token	Get agent profile
/api/agents/profile	PUT	Bearer Token	Update agent profile

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "error": "error_code",
  "error_description": "Human-readable error message"
}

Common Error Codes

invalid_request · 400

The request is missing required parameters or contains invalid values

invalid_client · 401

Client authentication failed or client ID not found

invalid_grant · 401

Invalid authorization code, refresh token, or PKCE verification failed

invalid_token · 401

Access token is invalid, expired, or revoked

insufficient_scope · 403

Token does not have required scopes for this operation

server_error · 500

Internal server error occurred

Rate Limiting

Rate limits are enforced per IP address and per client:

Registration · 5 requests / hour

Agent registration is limited to prevent abuse

Authentication · 10 requests / minute

Failed authentication attempts are rate limited

Token Refresh · 60 requests / hour

Token refresh requests per client

API Calls · 1000 requests / hour

General API calls with valid authentication

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1699564800

CORS Policy

The server supports CORS for browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 600

In production, configure specific origins instead of wildcard (*) for better security.

Scopes

OAuth scopes control access to user data:

openid · required

Required for OpenID Connect. Provides sub claim.

profile

Access to user profile information (name, agent_id, model_name)

email

Access to user email address

permissions

Access to user permissions array

Scope Format

Multiple scopes are space-separated:

openid profile email permissions

Testing

Test with cURL

# Register agent
curl -X POST https://api.auth-agent.com/api/register-agent \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "test_agent",
    "agent_secret": "Test123456!",
    "model_name": "gpt-4",
    "owner_name": "Test User",
    "owner_email": "[e-mail]"
  }'

# Get user info
curl https://api.auth-agent.com/oauth2/userinfo \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Postman Collection

Download our Postman Collection with pre-configured requests.

SDK Support

Instead of calling the API directly, use our official SDKs:

JavaScript/TypeScript

For browsers and Node.js

React

Hooks and components

Python

For Python applications

Webhooks

Webhook support is coming soon. Subscribe to our newsletter to be notified when available.

API Versioning

Current API version: v1

The API version is included in the base URL. We maintain backward compatibility within major versions.

Next Steps

OAuth Endpoints

Detailed OAuth 2.1 endpoint documentation

Agent Endpoints

Agent registration and management