Authentication Overview

​

Overview

• Local Authentication - Email and password-based authentication
• OAuth 2.0 - GitHub, Google, and Microsoft OAuth providers
• JWT Tokens - JSON Web Tokens for stateless authentication

​

Authentication Flow

​

Local Authentication

1. User signs up with email and password via /auth/signup
2. User logs in with credentials via /auth/login
3. Server returns a JWT access token
4. Client includes token in Authorization header for subsequent requests

​

OAuth Authentication

1. Client initiates OAuth flow via /auth/oauth/{provider}
2. Server returns authorization URL and state token
3. User completes OAuth flow with provider
4. Provider redirects to /auth/oauth/{provider}/callback with authorization code
5. Server exchanges code for access token and returns JWT

​

Token Management

​

Token Structure

• jti - Unique token identifier
• user_id - User UUID
• role - User role name
• auth_provider - Authentication provider (local, github, google, microsoft)
• token_version - Token version for revocation
• exp - Expiration timestamp
• iat - Issued at timestamp

​

Token Revocation

1. Individual revocation - Logout endpoint revokes specific token by JTI
2. Bulk revocation - Password updates increment token_version, invalidating all previous tokens

​

Authentication Providers

​

Available Providers

​

Provider Configuration

• Client ID - OAuth application identifier
• Client Secret - OAuth application secret
• Redirect URI - Callback URL for OAuth flow
• Tenant ID - (Microsoft only) Azure AD tenant identifier

​

Security Features

​

Password Requirements

• Minimum 12 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one digit
• At least one special character: !@#$%^&*(),.?":{}|<>

​

Password Hashing

​

Token Expiration

​

Common Endpoints

​

List Providers

curl -X GET https://api.example.com/auth/providers

{
  "providers": ["local", "github", "google", "microsoft"]
}

​

Get Current User

curl -X GET https://api.example.com/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "is_active": true,
  "role": "Basic User",
  "auth_identities": ["local", "github"]
}

​

Logout

curl -X POST https://api.example.com/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "message": "Logged out successfully"
}

​

Error Handling

​

Common Error Responses

{
  "detail": "Invalid email or password"
}

{
  "detail": "Could not validate credentials"
}

{
  "detail": "Local authentication is disabled"
}

​

Next Steps