API Endpoints¶

Complete reference for all OAuth2 Server REST API endpoints.

Base URL¶

http://localhost:8080

For production, use your deployed server URL with HTTPS:

https://oauth.your-domain.com

Endpoint Categories¶

OAuth2 Endpoints¶

Authorization Endpoint¶

Initiate the authorization code flow.

Endpoint: GET /oauth/authorize

Parameters:

Example:

GET /oauth/authorize?response_type=code&client_id=abc123&redirect_uri=http://localhost:3000/callback&scope=read%20write&state=xyz789 HTTP/1.1

Response:

HTTP/1.1 302 Found
Location: http://localhost:3000/callback?code=AUTH_CODE&state=xyz789

Token Endpoint¶

Exchange authorization code, refresh token, or credentials for access token.

Endpoint: POST /oauth/token

Content-Type: application/x-www-form-urlencoded

Authorization Code Grant¶

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=http://localhost:3000/callback&
client_id=abc123&
client_secret=secret123

Client Credentials Grant¶

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=abc123&
client_secret=secret123&
scope=read

Refresh Token Grant¶

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=abc123&
client_secret=secret123

Password Grant¶

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
username=user@example.com&
password=password123&
client_id=abc123&
client_secret=secret123

Success Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_abc123",
  "scope": "read write"
}

Error Response:

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid"
}

Token Introspection¶

Validate and get metadata about an access token.

Endpoint: POST /oauth/introspect

Parameters:

Example:

curl -X POST http://localhost:8080/oauth/introspect \
  -d "token=ACCESS_TOKEN" \
  -d "client_id=abc123" \
  -d "client_secret=secret123"

Response (Active Token):

{
  "active": true,
  "scope": "read write",
  "client_id": "abc123",
  "username": "user@example.com",
  "exp": 1704067200,
  "iat": 1704063600,
  "sub": "user-id-123"
}

Response (Inactive Token):

{
  "active": false
}

Token Revocation¶

Revoke an access or refresh token.

Endpoint: POST /oauth/revoke

Parameters:

Example:

curl -X POST http://localhost:8080/oauth/revoke \
  -d "token=ACCESS_TOKEN" \
  -d "client_id=abc123" \
  -d "client_secret=secret123"

Response:

HTTP/1.1 200 OK

Client Management¶

Register Client¶

Register a new OAuth2 client.

Endpoint: POST /clients/register

Request Body:

{
  "client_name": "My Application",
  "redirect_uris": [
    "http://localhost:3000/callback",
    "http://localhost:3000/silent-renew"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "scope": "read write profile"
}

Response:

{
  "client_id": "abc123def456",
  "client_secret": "secret_xyz789",
  "client_name": "My Application",
  "redirect_uris": [
    "http://localhost:3000/callback",
    "http://localhost:3000/silent-renew"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "scope": "read write profile",
  "created_at": "2024-01-01T00:00:00Z"
}

Discovery Endpoint¶

OpenID Configuration¶

Get OAuth2 server metadata.

Endpoint: GET /.well-known/openid-configuration

Response:

{
  "issuer": "http://localhost:8080",
  "authorization_endpoint": "http://localhost:8080/oauth/authorize",
  "token_endpoint": "http://localhost:8080/oauth/token",
  "introspection_endpoint": "http://localhost:8080/oauth/introspect",
  "revocation_endpoint": "http://localhost:8080/oauth/revoke",
  "jwks_uri": "http://localhost:8080/.well-known/jwks.json",
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token",
    "password"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "HS256"
  ],
  "scopes_supported": [
    "read",
    "write",
    "profile",
    "email"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "code_challenge_methods_supported": [
    "S256",
    "plain"
  ]
}

Admin Endpoints¶

Admin Dashboard¶

Web-based administration interface.

Endpoint: GET /admin

Response: HTML dashboard page

Health Check¶

Check if the server is healthy.

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "database": "connected",
  "version": "0.1.0",
  "timestamp": "2024-01-01T00:00:00Z"
}

Readiness Check¶

Check if the server is ready to accept requests.

Endpoint: GET /ready

Response:

{
  "ready": true,
  "database": "ready",
  "timestamp": "2024-01-01T00:00:00Z"
}

Metrics¶

Prometheus metrics endpoint.

Endpoint: GET /metrics

Response: Prometheus text format metrics

Eventing Endpoints¶

These endpoints are only useful when eventing is enabled (OAUTH2_EVENTS_ENABLED=true).

Event System Health¶

Check event backend/plugin health.

Endpoint: GET /events/health

Response (disabled):

{
  "enabled": false,
  "plugins": []
}

Response (enabled):

{
  "enabled": true,
  "plugins": [
    {
      "name": "console",
      "healthy": true
    }
  ]
}

Ingest External Event¶

Submit an externally-produced event envelope to the server.

Endpoint: POST /events/ingest

Headers:

• Content-Type: application/json
• Idempotency-Key: <string> (recommended)

Body: EventEnvelope JSON (see docs/eventing.md for structure)

Response (accepted):

{
  "status": "accepted",
  "idempotency_key": "your-key",
  "event_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response (duplicate):

{
  "status": "duplicate",
  "idempotency_key": "your-key",
  "event_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response (eventing disabled):

{
  "error": "eventing_disabled"
}

Social Login Endpoints¶

Google Login¶

Initiate Google OAuth2 login.

Endpoint: GET /auth/login/google

Microsoft Login¶

Initiate Microsoft/Azure AD login.

Endpoint: GET /auth/login/microsoft

GitHub Login¶

Initiate GitHub OAuth login.

Endpoint: GET /auth/login/github

OAuth Callback¶

Handle OAuth provider callbacks.

Endpoint: GET /auth/callback/{provider}

Parameters:

Logout¶

End user session.

Endpoint: POST /auth/logout

Response:

HTTP/1.1 302 Found
Location: /auth/login

Swagger UI¶

Interactive API documentation.

Endpoint: GET /swagger-ui

Response: HTML Swagger UI page

Rate Limiting¶

All endpoints are subject to rate limiting:

• Authorization endpoint: 10 requests per minute per IP
• Token endpoint: 20 requests per minute per client
• Introspection: 100 requests per minute per client
• Other endpoints: 100 requests per minute per IP

Rate Limit Response:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Please try again later."
}

Error Responses¶

All endpoints return errors in the following format:

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

Common Error Codes¶

Authentication¶

Most endpoints require client authentication via:

1. Client Credentials in Body¶

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=abc123&client_secret=secret123&...

2. Basic Authentication¶

POST /oauth/token
Authorization: Basic YWJjMTIzOnNlY3JldDEyMw==
Content-Type: application/x-www-form-urlencoded

grant_type=...

3. Bearer Token¶

For protected resources:

GET /api/resource
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Next Steps¶

• Authentication Details - Token usage and scopes
• Error Handling - Comprehensive error reference
• OAuth2 Flows - Flow documentation
• API Examples - Usage examples