OAuth2 Server Documentation
A comprehensive OAuth2 authorization server implementation supporting multiple grant types and complete user, client, and token management.
Features
OAuth2 Grant Types Support
- Authorization Code Grant
- Client Credentials Grant
- Password Grant (Resource Owner Password Credentials)
- Refresh Token Grant
Client Management
- Client registration and authentication
- Multiple redirect URIs support
- Grant type restrictions
- Scope-based access control
- Confidential and public client support
User Management
- User registration and authentication
- Role-based access control
- Password reset functionality
- Email verification
- Profile management
Token Management
- Access token generation and validation
- Refresh token handling
- Token introspection
- Token revocation (single and bulk)
- Active session management
Security Features
- Rate limiting
- Audit logging
- Session management
- Basic authentication support
- Scope-based authorization
- Token introspection
Consent Management
- User consent tracking
- Granular permission control
- Consent revocation
- Consent history
API Documentation
OAuth2 Endpoints
Token Endpoint
POST /api/v1/oauth/tokens
Authorization: Basic {client_credentials}
Content-Type: application/x-www-form-urlencoded
Supported grant types:
- Authorization Code
grant_type=authorization_code
code={authorization_code}
redirect_uri={redirect_uri}
- Client Credentials
grant_type=client_credentials
scope={scope}
- Password
grant_type=password
username={username}
password={password}
scope={scope}
- Refresh Token
grant_type=refresh_token
refresh_token={refresh_token}
Token Introspection
POST /api/v1/oauth/introspect
Authorization: Basic {client_credentials}
Content-Type: application/x-www-form-urlencoded
token={token}
token_type_hint={access_token|refresh_token}
Client Management API
Register New Client
POST /api/v1/oauth/clients
Content-Type: application/json
{
"name": "My Application",
"redirect_uris": ["https://app.example.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "read write",
"confidential": true
}
List Clients
GET /api/v1/oauth/clients
Update Client
PUT /api/v1/oauth/clients/{client_id}
Delete Client
DELETE /api/v1/oauth/clients/{client_id}
User Management API
Register User
POST /api/v1/users
Content-Type: application/json
{
"username": "john.doe@example.com",
"password": "secure_password",
"name": "John Doe",
"roles": ["user"]
}
User Operations
PUT /api/v1/users/profile # Update user profile
POST /api/v1/users/reset-password # Reset password
POST /api/v1/users/verify-email # Verify email
GET /api/v1/users # List users (admin only)
PUT /api/v1/users/{user_id} # Update user (admin only)
DELETE /api/v1/users/{user_id} # Delete user (admin only)
Scope Management API
Create Scope
POST /api/v1/oauth/scopes
Content-Type: application/json
{
"name": "read_profile",
"description": "Read user profile information"
}
Scope Operations
GET /api/v1/oauth/scopes # List scopes
PUT /api/v1/oauth/scopes/{scope_id} # Update scope
DELETE /api/v1/oauth/scopes/{scope_id} # Delete scope
Consent Management API
Create Consent
POST /api/v1/oauth/consents
Content-Type: application/json
{
"client_id": "client_id",
"scopes": ["read", "write"]
}
Consent Operations
GET /api/v1/oauth/consents # List consents
DELETE /api/v1/oauth/consents/{consent_id} # Revoke consent
Security & Monitoring API
Token Management
GET /api/v1/oauth/tokens # List active tokens
POST /api/v1/oauth/tokens/revoke # Revoke specific token
POST /api/v1/oauth/tokens/bulk-revoke # Bulk revoke tokens
Monitoring
GET /api/v1/audit-logs # View audit logs
GET /api/v1/oauth/rate-limits # Check rate limit status
GET /api/v1/oauth/sessions # List active sessions
DELETE /api/v1/oauth/sessions/{session_id} # End session
Authentication
Most endpoints require authentication using HTTP Basic Authentication with client credentials:
Authorization: Basic base64(client_id:client_secret)
Error Handling
The API uses standard HTTP status codes and returns errors in the following format:
{
"error": "error_code",
"error_description": "Detailed error message",
"error_uri": "https://documentation/errors/error_code"
}
Rate Limiting
The API implements rate limiting per client. Current limits can be checked via the rate-limiting endpoint.
Security Considerations
- Always use HTTPS in production
- Implement proper password hashing
- Store client secrets securely
- Implement token encryption
- Set up proper CORS configuration
- Enable audit logging
- Implement IP whitelisting where appropriate
Database Schema
The server requires the following database tables:
- users
- clients
- access_tokens
- refresh_tokens
- authorization_codes
- scopes
- client_scopes
- user_consents
- audit_logs