Management API

Complete reference for user, client, and MFA management endpoints.

Base URL & Authentication

Base URL

https://api.oauth42.com

Authentication

All management API requests require authentication using a Bearer token:

Authorization: Bearer ACCESS_TOKEN

User Management

GET/api/users

List all users with pagination and filtering options.

Query Parameters

page- Page number (default: 1)
limit- Results per page (default: 25, max: 100)
search- Search by name or email
email_verified- Filter by email verification status

Example Request

GET /api/users?page=1&limit=25&search=john
Authorization: Bearer ACCESS_TOKEN

Success Response (200 OK)

{
  "users": [
    {
      "id": "user_12345",
      "email": "[email protected]",
      "email_verified": true,
      "name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "picture": "https://example.com/avatar.jpg",
      "mfa_enabled": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z",
      "last_login": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 100,
    "totalPages": 4
  }
}
GET/api/users/:id

Get detailed information about a specific user.

Success Response (200 OK)

{
  "id": "user_12345",
  "email": "[email protected]",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://example.com/avatar.jpg",
  "phone_number": "+1234567890",
  "phone_verified": false,
  "mfa_enabled": true,
  "mfa_methods": ["totp"],
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z",
  "last_login": "2025-01-15T10:30:00Z",
  "login_count": 42
}
POST/api/users

Create a new user account.

Request Body

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "name": "Jane Smith",
  "given_name": "Jane",
  "family_name": "Smith",
  "picture": "https://example.com/avatar.jpg",
  "email_verified": false,
  "send_verification_email": true
}

Success Response (201 Created)

{
  "id": "user_67890",
  "email": "[email protected]",
  "email_verified": false,
  "name": "Jane Smith",
  "created_at": "2025-01-15T12:30:00Z"
}
PATCH/api/users/:id

Update user information (partial update).

Request Body

{
  "name": "Jane Doe",
  "picture": "https://example.com/new-avatar.jpg"
}

Success Response (200 OK)

{
  "id": "user_67890",
  "email": "[email protected]",
  "name": "Jane Doe",
  "picture": "https://example.com/new-avatar.jpg",
  "updated_at": "2025-01-15T13:00:00Z"
}
DELETE/api/users/:id

Delete a user account permanently. This action cannot be undone.

Success Response (200 OK)

{
  "success": true,
  "message": "User deleted successfully"
}

OAuth Client Management

GET/api/clients

List all OAuth clients for the authenticated user or organization.

Success Response (200 OK)

{
  "clients": [
    {
      "client_id": "client_abc123",
      "client_name": "My Application",
      "client_type": "confidential",
      "redirect_uris": [
        "https://myapp.com/callback"
      ],
      "grant_types": ["authorization_code", "refresh_token"],
      "scopes": ["openid", "profile", "email"],
      "logo_uri": "https://myapp.com/logo.png",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-10T08:00:00Z"
    }
  ]
}
GET/api/clients/:id

Get detailed information about a specific OAuth client.

Success Response (200 OK)

{
  "client_id": "client_abc123",
  "client_name": "My Application",
  "client_type": "confidential",
  "redirect_uris": [
    "https://myapp.com/callback",
    "https://myapp.com/auth/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "scopes": ["openid", "profile", "email"],
  "token_endpoint_auth_method": "client_secret_post",
  "logo_uri": "https://myapp.com/logo.png",
  "tos_uri": "https://myapp.com/terms",
  "policy_uri": "https://myapp.com/privacy",
  "jwks_uri": "https://myapp.com/.well-known/jwks.json",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-10T08:00:00Z"
}
POST/api/clients

Create a new OAuth client application.

Request Body

{
  "client_name": "New Application",
  "client_type": "confidential",
  "redirect_uris": [
    "https://newapp.com/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "scopes": ["openid", "profile", "email"],
  "logo_uri": "https://newapp.com/logo.png"
}

Success Response (201 Created)

{
  "client_id": "client_xyz789",
  "client_secret": "secret_abcdef123456",
  "client_name": "New Application",
  "client_type": "confidential",
  "redirect_uris": ["https://newapp.com/callback"],
  "created_at": "2025-01-15T14:00:00Z"
}

⚠️ Important

The client_secret is only shown once during creation. Store it securely - you won't be able to retrieve it again.

PATCH/api/clients/:id

Update OAuth client configuration.

Request Body

{
  "client_name": "Updated Application Name",
  "redirect_uris": [
    "https://newapp.com/callback",
    "https://newapp.com/auth/callback"
  ]
}

Success Response (200 OK)

{
  "client_id": "client_xyz789",
  "client_name": "Updated Application Name",
  "redirect_uris": [
    "https://newapp.com/callback",
    "https://newapp.com/auth/callback"
  ],
  "updated_at": "2025-01-15T15:00:00Z"
}
POST/api/clients/:id/rotate-secret

Generate a new client secret and invalidate the old one.

Success Response (200 OK)

{
  "client_id": "client_xyz789",
  "client_secret": "secret_newvalue987654",
  "rotated_at": "2025-01-15T16:00:00Z"
}
DELETE/api/clients/:id

Delete an OAuth client permanently. All associated tokens will be revoked.

Success Response (200 OK)

{
  "success": true,
  "message": "Client deleted successfully"
}

Multi-Factor Authentication

POST/api/mfa/setup

Initiate MFA setup for the authenticated user. Generates TOTP secret and backup codes.

Success Response (200 OK)

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,iVBORw0KG...",
  "backupCodes": [
    "1234-5678",
    "9012-3456",
    "5678-9012",
    "3456-7890",
    "7890-1234"
  ]
}
POST/api/mfa/verify-setup

Verify MFA setup by providing a TOTP code from the authenticator app.

Request Body

{
  "code": "123456"
}

Success Response (200 OK)

{
  "success": true,
  "enabled": true,
  "message": "MFA enabled successfully"
}
POST/api/mfa/disable

Disable MFA for the authenticated user. Requires MFA verification.

Request Body

{
  "code": "123456"
}

Success Response (200 OK)

{
  "success": true,
  "enabled": false,
  "message": "MFA disabled successfully"
}
POST/api/mfa/backup-codes/regenerate

Generate new backup codes. Old codes will be invalidated.

Success Response (200 OK)

{
  "backupCodes": [
    "2345-6789",
    "0123-4567",
    "6789-0123",
    "4567-8901",
    "8901-2345"
  ]
}

Session Management

GET/api/sessions

List all active sessions for the authenticated user.

Success Response (200 OK)

{
  "sessions": [
    {
      "id": "session_abc123",
      "device_name": "Chrome on MacOS",
      "ip_address": "203.0.113.0",
      "location": "San Francisco, CA",
      "last_accessed": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-10T08:00:00Z",
      "is_current": true
    },
    {
      "id": "session_def456",
      "device_name": "Safari on iPhone",
      "ip_address": "203.0.113.42",
      "location": "Los Angeles, CA",
      "last_accessed": "2025-01-14T18:20:00Z",
      "created_at": "2025-01-08T12:00:00Z",
      "is_current": false
    }
  ]
}
DELETE/api/sessions/:id

Revoke a specific session and invalidate all associated tokens.

Success Response (200 OK)

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

Next Steps

Authentication API

OAuth 2.0 and OpenID Connect endpoints

WebSocket Events

Real-time event notifications via WebSocket

MFA Guide

Learn how to implement multi-factor authentication