OAuth 2.0 / 3LO API Reference

Complete API reference for OAuth provider management, authentication flows, and audit logging.

📘 Documentation Scope: This guide covers the core OAuth endpoints used in the 20 most commonly used workflows. Advanced OAuth features (user management, analytics, detailed audit logs) will be expanded in future releases.

OAuth API Base URL

http://localhost:8080/api/v1

For production, replace with your domain:

https://gateway.company.com/api/v1

OAuth API Authentication

OAuth endpoints have mixed authentication requirements:

Protected Endpoints (Admin Authentication Required)

All OAuth management endpoints require admin authentication:

bash

# Admin JWT token or OAuth session token with admin role
Authorization: Bearer YOUR_ADMIN_TOKEN

Protected Endpoints:

OAuth provider management (create, update, delete providers)
OAuth user management
OAuth analytics and audit logs
Session management (list, revoke sessions)

Public Endpoints (No Authentication Required)

OAuth flow endpoints are public to allow user authentication:

Public Endpoints:

POST /api/v1/oauth/authorize - Initiate OAuth flow
GET /api/v1/oauth/callback - OAuth provider callback
POST /api/v1/oauth/validate - Validate session token
POST /api/v1/oauth/refresh - Refresh OAuth token
POST /api/v1/oauth/logout - Logout (invalidate session)
POST /api/v1/oauth/register - Dynamic Client Registration (DCR)
GET /api/v1/oauth/health - OAuth health check
GET /.well-known/jwks.json - JSON Web Key Set (public key distribution)
GET /.well-known/openid-configuration - OpenID Connect discovery document

Hybrid Authentication

Important: OAuth session tokens work interchangeably with admin JWT tokens:

bash

# Admin JWT token (from /api/v1/auth/login)
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:8080/api/v1/proxies/

# OAuth session token (from OAuth login)
curl -H "Authorization: Bearer <oauth-session-token>" \
  http://localhost:8080/api/v1/proxies/

# Both work identically - no difference in API usage

See Also: Authentication Guide for complete authentication documentation.

OAuth Provider Management

List OAuth Providers

Get all configured OAuth providers.

Endpoint: GET /oauth/providers

Response:

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "GitHub Enterprise",
      "provider_type": "github",
      "client_id": "Iv1.abc123...",
      "auth_url": "https://github.com/login/oauth/authorize",
      "token_url": "https://github.com/login/oauth/access_token",
      "userinfo_url": "https://api.github.com/user",
      "redirect_uri": "http://localhost:8080/api/v1/oauth/callback",
      "scopes": ["read:user", "user:email"],
      "enabled": true,
      "created_at": "2025-10-24T10:00:00Z",
      "updated_at": "2025-10-24T10:00:00Z"
    }
  ]
}

Get OAuth Provider

Get details of a specific OAuth provider.

Endpoint: GET /oauth/providers/{id}

Response:

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "GitHub Enterprise",
    "provider_type": "github",
    "client_id": "Iv1.abc123...",
    "enabled": true,
    "scopes": ["read:user", "user:email"]
  }
}

Create OAuth Provider

Create a new OAuth provider configuration.

Endpoint: POST /oauth/providers

IMPORTANT - Redirect URI Format: The OAuth callback URL is a clean URL without query parameters. The backend automatically tracks which OAuth provider is being used via secure server-side state storage.

Example Redirect URIs:

http://localhost:8080/api/v1/oauth/callback
https://gateway.company.com/api/v1/oauth/callback
http://moo.cow:9191/api/v1/oauth/callback

Request Body (Template Mode):

json

{
  "name": "GitHub Enterprise",
  "provider_type": "github",
  "client_id": "Iv1.abc123...",
  "client_secret": "secret123...",
  "redirect_uri": "http://localhost:8080/api/v1/oauth/callback",
  "use_template": true
}

Note: Use the same redirect_uri that you configured in your OAuth provider settings (GitHub, Google, Okta, etc.). This URL must be an exact match.

Request Body (Manual Mode):

json

{
  "name": "Custom OAuth Provider",
  "provider_type": "custom",
  "client_id": "client_id_here",
  "client_secret": "client_secret_here",
  "auth_url": "https://provider.com/oauth/authorize",
  "token_url": "https://provider.com/oauth/token",
  "userinfo_url": "https://provider.com/oauth/userinfo",
  "redirect_uri": "http://localhost:8080/api/v1/oauth/callback",
  "scopes": ["openid", "profile", "email"],
  "use_template": false
}

Response:

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "GitHub Enterprise",
    "provider_type": "github",
    "enabled": true
  },
  "message": "OAuth provider created successfully"
}

Configuration Verification: After creating the provider, verify your OAuth provider settings:

Ensure the redirect URI in your OAuth provider dashboard (GitHub, Google, Okta, etc.) matches exactly
No additional query parameters should be added to the callback URL
Example: http://localhost:8080/api/v1/oauth/callback (exact match required)

Update OAuth Provider

Update an existing OAuth provider.

Endpoint: PUT /oauth/providers/{id}

Request Body:

json

{
  "name": "GitHub Enterprise Updated",
  "enabled": true,
  "scopes": ["read:user", "user:email", "read:org"]
}

Response:

json

{
  "success": true,
  "message": "OAuth provider updated successfully"
}

Delete OAuth Provider

Delete an OAuth provider and invalidate all its sessions.

Endpoint: DELETE /oauth/providers/{id}

Response:

json

{
  "success": true,
  "message": "OAuth provider deleted successfully"
}

Get Provider Templates

Get available OAuth provider templates.

Endpoint: GET /oauth/providers/templates

Response:

json

{
  "success": true,
  "data": [
    {
      "name": "GitHub",
      "provider_type": "github",
      "description": "GitHub OAuth 2.0",
      "default_scopes": ["read:user", "user:email"]
    },
    {
      "name": "Google",
      "provider_type": "google",
      "description": "Google OAuth 2.0 / OpenID Connect",
      "default_scopes": ["openid", "profile", "email"]
    }
  ]
}

Get Provider Setup Documentation

Get setup instructions for a specific provider type.

Endpoint: GET /oauth/providers/templates/{type}/docs

Response:

json

{
  "success": true,
  "data": {
    "provider_type": "github",
    "documentation": "1. Go to GitHub Settings → Developer Settings...",
    "required_scopes": ["read:user", "user:email"],
    "callback_url": "http://localhost:8080/api/v1/oauth/callback"
  }
}

OAuth Flow Endpoints

Initiate OAuth Flow

Start the OAuth authorization flow.

Endpoint: POST /oauth/authorize

Request Body:

json

{
  "provider_id": 1,
  "user_group_id": 5,
  "redirect_uri": "http://localhost:8080/api/v1/oauth/callback"
}

Response:

json

{
  "success": true,
  "data": {
    "auth_url": "https://github.com/login/oauth/authorize?client_id=...&state=...",
    "state": "random_state_token"
  }
}

User Action: Redirect browser to auth_url for authentication.

OAuth Callback Handler

Handle OAuth provider callback (automatic).

Endpoint: GET /oauth/callback

Query Parameters:

code - Authorization code from provider
state - CSRF protection state token
format (optional) - Response format: json (default: HTML page)

Response (v1.1.0+):

Default (HTML Page) - User-friendly success page with:

Session token display with copy button
User information (email, name, role)
Token expiration details
Context-aware instructions
Dashboard link (production mode)

JSON Format (via ?format=json or Accept: application/json):

json

{
  "success": true,
  "data": {
    "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "jwt_id": "abc-123-def",
    "user_identity": "alice@company.com",
    "expires_at": "2025-11-10T10:00:00Z"
  }
}

Note: Prior to v1.1.0, this endpoint returned JSON by default. For backward compatibility, use ?format=json query parameter or set Accept: application/json header.

Validate Session

Validate an OAuth session token.

Endpoint: POST /oauth/validate

Request Body:

json

{
  "session_token": "session_token_here"
}

Response:

json

{
  "success": true,
  "data": {
    "valid": true,
    "user_identity": "alice@company.com",
    "user_email": "alice@company.com",
    "user_name": "Alice Smith",
    "expires_at": "2025-10-24T15:00:00Z"
  }
}

Refresh Token

Refresh an expired access token.

Endpoint: POST /oauth/refresh

Request Body:

json

{
  "session_token": "session_token_here"
}

Response:

json

{
  "success": true,
  "message": "Token refreshed successfully"
}

Logout

Invalidate an OAuth session.

Endpoint: POST /oauth/logout

Request Body:

json

{
  "session_token": "session_token_here"
}

Response:

json

{
  "success": true,
  "message": "Logged out successfully"
}

JWKS (JSON Web Key Set)

The Gateway provides public endpoints for JWT key discovery, enabling external services to verify JWTs issued by the Gateway without shared secrets.

Get JWKS

Retrieve the JSON Web Key Set containing public keys for JWT verification.

Endpoint: GET /.well-known/jwks.json

Authentication: None (public endpoint)

Response (RSA mode):

json

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "gateway-key-v1",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFb...",
      "e": "AQAB"
    }
  ]
}

Response (HMAC mode - default):

json

{
  "keys": [
    {
      "kty": "oct",
      "use": "sig",
      "kid": "gateway-key-v1",
      "alg": "HS256",
      "key_ops": ["sign", "verify"]
    }
  ]
}

RSA Mode

To enable RSA signing and expose public keys:

bash

openssl genrsa -out private.pem 2048
export JWT_RSA_PRIVATE_KEY_FILE=/path/to/private.pem

Get OpenID Configuration

Retrieve OpenID Connect discovery document with metadata about the Gateway's OAuth capabilities.

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

Authentication: None (public endpoint)

Response:

json

{
  "issuer": "ai-security-gateway",
  "jwks_uri": "http://localhost:8080/.well-known/jwks.json",
  "authorization_endpoint": "http://localhost:8080/oauth/authorize",
  "token_endpoint": "http://localhost:8080/oauth/token",
  "response_types_supported": ["code", "token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["HS256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "claims_supported": [
    "sub", "email", "name", "role", "org", "iss", "aud", "exp", "iat", "jti"
  ],
  "scopes_supported": ["openid", "profile", "email"]
}

Session Management

Get Provider Sessions

Get all active sessions for an OAuth provider.

Endpoint: GET /oauth/providers/{id}/sessions

Query Parameters:

active (optional) - Filter active sessions only (true/false)

Response:

json

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "user_identity": "alice@company.com",
        "user_email": "alice@company.com",
        "user_name": "Alice Smith",
        "created_at": "2025-10-24T10:00:00Z",
        "last_used": "2025-10-24T14:30:00Z",
        "expires_at": "2025-10-24T15:00:00Z"
      }
    ],
    "total": 1
  }
}

Get User Sessions

Get all sessions for a specific user.

Endpoint: GET /oauth/sessions/user/{identity}

Response:

json

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "provider_name": "GitHub Enterprise",
        "created_at": "2025-10-24T10:00:00Z",
        "expires_at": "2025-10-24T15:00:00Z"
      }
    ]
  }
}

Revoke Session

Revoke a specific OAuth session.

Endpoint: DELETE /oauth/sessions/{id}

Response:

json

{
  "success": true,
  "message": "Session revoked successfully"
}

Get Session Statistics

Get aggregate session statistics.

Endpoint: GET /oauth/sessions/stats

Response:

json

{
  "success": true,
  "data": {
    "total_sessions": 45,
    "active_sessions": 23,
    "expired_sessions": 22,
    "unique_users": 15
  }
}

Cleanup Expired Sessions

Remove all expired sessions from database.

Endpoint: POST /oauth/sessions/cleanup

Response:

json

{
  "success": true,
  "data": {
    "deleted_count": 22
  },
  "message": "Cleaned up 22 expired sessions"
}

Audit & Reporting

Get Audit Logs

Get paginated audit logs with optional filtering.

Endpoint: GET /oauth/audit/logs

Query Parameters:

page (optional) - Page number (default: 1)
limit (optional) - Results per page (default: 50, max: 500)
user (optional) - Filter by user identity or email
proxy_id (optional) - Filter by proxy ID
mcp_tool (optional) - Filter by MCP tool name
blocked (optional) - Filter blocked requests (true/false)
min_risk_score (optional) - Minimum risk score
start_date (optional) - Start date (ISO 8601)
end_date (optional) - End date (ISO 8601)

Response:

json

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": 1,
        "created_at": "2025-10-24T14:30:00Z",
        "user_identity": "alice@company.com",
        "user_email": "alice@company.com",
        "proxy_config_id": 1,
        "method": "POST",
        "request_path": "/tools/call",
        "mcp_tool": "database_query",
        "response_status": 200,
        "duration_ms": 45,
        "blocked": false,
        "risk_score": 35
      }
    ],
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

Get Audit Log Details

Get detailed information for a specific audit log entry.

Endpoint: GET /oauth/audit/logs/{id}

Response:

json

{
  "success": true,
  "data": {
    "id": 1,
    "created_at": "2025-10-24T14:30:00Z",
    "user_identity": "alice@company.com",
    "user_email": "alice@company.com",
    "request_path": "/tools/call",
    "request_payload": "{\"tool\":\"database_query\",\"params\":{}}",
    "response_status": 200,
    "blocked": false,
    "block_reason": null,
    "risk_score": 35,
    "policy_hits": ["sql-injection-check"]
  }
}

Get all actions performed by a specific user.

Endpoint: GET /oauth/audit/user/{identity}

Query Parameters:

start_date (optional) - Start date filter
end_date (optional) - End date filter
limit (optional) - Max results (default: 100)

Response:

json

{
  "success": true,
  "data": {
    "user_identity": "alice@company.com",
    "user_email": "alice@company.com",
    "total_actions": 156,
    "blocked_actions": 3,
    "actions": [
      {
        "timestamp": "2025-10-24T14:30:00Z",
        "proxy_name": "Production MCP",
        "mcp_tool": "database_query",
        "blocked": false,
        "risk_score": 35
      }
    ]
  }
}

Get Proxy Access History

Get all users who accessed a specific proxy.

Endpoint: GET /oauth/audit/proxy/{id}

Query Parameters:

start_date (optional) - Start date filter
end_date (optional) - End date filter

Response:

json

{
  "success": true,
  "data": {
    "proxy_id": 1,
    "proxy_name": "Production MCP",
    "unique_users": 5,
    "users": [
      {
        "user_identity": "alice@company.com",
        "user_email": "alice@company.com",
        "first_access": "2025-10-20T10:00:00Z",
        "last_access": "2025-10-24T14:30:00Z",
        "total_requests": 156,
        "blocked_requests": 3
      }
    ]
  }
}

Get Audit Statistics

Get aggregate audit statistics.

Endpoint: GET /oauth/audit/stats

Query Parameters:

days (optional) - Number of days to analyze (default: 7)

Response:

json

{
  "success": true,
  "data": {
    "active_users": 15,
    "total_actions": 1234,
    "proxies_accessed": 8,
    "blocked_requests": 23,
    "average_risk_score": 18.5,
    "top_users": [
      {
        "user_identity": "alice@company.com",
        "action_count": 156
      }
    ]
  }
}

Get Top MCP Tools

Get most used MCP tools by user.

Endpoint: GET /oauth/audit/tools/top

Query Parameters:

limit (optional) - Number of results (default: 10)
days (optional) - Days to analyze (default: 7)

Response:

json

{
  "success": true,
  "data": [
    {
      "tool_name": "database_query",
      "usage_count": 234,
      "unique_users": 8,
      "average_risk_score": 32
    }
  ]
}

Get Top Users

Get most active users.

Endpoint: GET /oauth/audit/users/top

Query Parameters:

limit (optional) - Number of results (default: 10)
days (optional) - Days to analyze (default: 7)

Response:

json

{
  "success": true,
  "data": [
    {
      "user_identity": "alice@company.com",
      "user_email": "alice@company.com",
      "action_count": 156,
      "last_active": "2025-10-24T14:30:00Z"
    }
  ]
}

Export Audit Logs

Export audit logs in CSV or JSON format.

Endpoint: GET /oauth/audit/export

Query Parameters:

format - Export format (csv or json)
user (optional) - Filter by user
proxy_id (optional) - Filter by proxy
start_date (optional) - Start date
end_date (optional) - End date

Response: File download with Content-Disposition header

Example:

bash

curl -X GET "http://localhost:8080/api/v1/oauth/audit/export?format=csv&start_date=2025-10-01" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o audit-logs.csv

OAuth Error Responses

All endpoints return consistent error format:

json

{
  "success": false,
  "error": "Error message here",
  "code": "ERROR_CODE"
}

OAuth Common Error Codes

Code	Description
`PROVIDER_NOT_FOUND`	OAuth provider doesn't exist
`INVALID_CREDENTIALS`	Invalid client ID or secret
`INVALID_STATE`	CSRF state token mismatch
`SESSION_EXPIRED`	OAuth session has expired
`TOKEN_REFRESH_FAILED`	Unable to refresh access token
`UNAUTHORIZED`	Missing or invalid authentication
`VALIDATION_ERROR`	Request validation failed

Rate Limits

OAuth Flow Endpoints: 10 requests per minute per IP
Management Endpoints: 100 requests per minute per token
Audit Endpoints: 60 requests per minute per token

Webhooks (Future)

Webhook support for OAuth events:

oauth.session.created
oauth.session.expired
oauth.token.refreshed
oauth.user.blocked

Coming in future release.

OAuth 2.0 / 3LO API Reference ​

OAuth API Base URL ​

OAuth API Authentication ​

Protected Endpoints (Admin Authentication Required) ​

Public Endpoints (No Authentication Required) ​

Hybrid Authentication ​

OAuth Provider Management ​

List OAuth Providers ​

Get OAuth Provider ​

Create OAuth Provider ​

Update OAuth Provider ​

Delete OAuth Provider ​

Get Provider Templates ​

Get Provider Setup Documentation ​

OAuth Flow Endpoints ​

Initiate OAuth Flow ​

OAuth Callback Handler ​

Validate Session ​

Refresh Token ​

Logout ​

JWKS (JSON Web Key Set) ​

Get JWKS ​

Get OpenID Configuration ​

Session Management ​

Get Provider Sessions ​

Get User Sessions ​

Revoke Session ​

Get Session Statistics ​

Cleanup Expired Sessions ​

Audit & Reporting ​

Get Audit Logs ​

Get Audit Log Details ​

Get User Actions ​

Get Proxy Access History ​

Get Audit Statistics ​

Get Top MCP Tools ​

Get Top Users ​

Export Audit Logs ​

OAuth Error Responses ​

OAuth Common Error Codes ​

Rate Limits ​

Webhooks (Future) ​

OAuth API Related Documentation ​

OAuth 2.0 / 3LO API Reference

OAuth API Base URL

OAuth API Authentication

Protected Endpoints (Admin Authentication Required)

Public Endpoints (No Authentication Required)

Hybrid Authentication

OAuth Provider Management

List OAuth Providers

Get OAuth Provider

Create OAuth Provider

Update OAuth Provider

Delete OAuth Provider

Get Provider Templates

Get Provider Setup Documentation

OAuth Flow Endpoints

Initiate OAuth Flow

OAuth Callback Handler

Validate Session

Refresh Token

Logout

JWKS (JSON Web Key Set)

Get JWKS

Get OpenID Configuration

Session Management

Get Provider Sessions

Get User Sessions

Revoke Session

Get Session Statistics

Cleanup Expired Sessions

Audit & Reporting

Get Audit Logs

Get Audit Log Details

Get User Actions

Get Proxy Access History

Get Audit Statistics

Get Top MCP Tools

Get Top Users

Export Audit Logs

OAuth Error Responses

OAuth Common Error Codes

Rate Limits

Webhooks (Future)

OAuth API Related Documentation