API Reference
Complete reference documentation for all OAuth42 REST APIs and WebSocket events. Build secure authentication and user management features with our comprehensive API.
Getting Started
Base URL
https://auth.oauth42.comAll API requests should be made to this base URL. In development, use your local instance URL.
Authentication
Management API endpoints require authentication using an access token:
Authorization: Bearer <access_token>API Endpoints
Authentication & Authorization
OAuth 2.0 and OpenID Connect endpoints for user authentication and authorization
/oauth/authorize-Start OAuth 2.0 authorization flow/oauth/token-Exchange authorization code for tokens/oauth/revoke-Revoke access or refresh tokens/oauth/introspect-Validate and inspect tokens/oauth/userinfo-Get authenticated user informationDiscovery & Metadata
OpenID Connect discovery endpoints for dynamic configuration
/.well-known/openid-configuration-OpenID Connect discovery document/.well-known/jwks.json-JSON Web Key Set for token validationUser Management
Endpoints for managing user accounts, profiles, and sessions
/api/users-List users in your organization/api/users-Create a new user account/api/users/:id-Get user details/api/users/:id-Update user information/api/users/:id-Delete user account/api/users/:id/sessions-List active user sessionsMulti-Factor Authentication
Manage TOTP-based two-factor authentication for users
/api/mfa/setup-Initialize TOTP setup for user/api/mfa/verify-Verify and enable TOTP/api/mfa/disable-Disable MFA for user/api/mfa/backup-codes-Generate backup codesOAuth Clients
Manage OAuth 2.0 client applications and their configurations
/api/clients-List OAuth clients/api/clients-Create new OAuth client/api/clients/:id-Get client details/api/clients/:id-Update client configuration/api/clients/:id-Delete OAuth client/api/clients/:id/secret-Rotate client secretReal-Time Events
WebSocket connection for real-time authentication and session events
/ws-WebSocket connection endpointResponse Format
All API responses use JSON format with consistent structure. Successful responses include the requested data, while errors follow a standard error format.
Success Response
{
"data": {
"id": "user_123",
"email": "[email protected]",
"name": "John Doe"
}
}Error Response
{
"error": "invalid_request",
"error_description": "Missing required parameter",
"status": 400
}HTTP Status Codes
OK
Request succeeded
Created
Resource created successfully
Bad Request
Invalid request parameters
Unauthorized
Missing or invalid authentication
Forbidden
Insufficient permissions
Not Found
Resource does not exist
Too Many Requests
Rate limit exceeded
Internal Server Error
Server error occurred
Rate Limiting
API requests are rate limited to ensure fair usage and system stability. Rate limits are applied per API key and IP address.
Rate Limit Headers
Default Limits: 100 requests per minute for authenticated requests, 20 requests per minute for unauthenticated requests.
Official SDKs
We provide official SDKs that handle API authentication, error handling, and best practices for you.