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/users

Create a new user account. Supports both public signup (no authentication) and service account provisioning (requires write or admin scope).

📝 Two Authentication Modes

Public Signup: No authentication required. User provides password and receives email verification. Requires signup feature flag enabled.

Service Account: Requires Bearer token with write or admin scope. Random password generated automatically. Optional invitation email with activation link.

Request Body (Service Account)

{
  "email": "[email protected]",
  "username": "jsmith",                         // Optional
  "first_name": "Jane",                        // Optional
  "last_name": "Smith",                        // Optional
  "phone": "+1234567890",                      // Optional
  "is_active": true,                           // Optional (default: true)
  "send_invitation": true,                     // Optional - Send email with activation link
  "default_group_id": "550e8400-e29b-41d4-...", // Optional - Add user to group
  "application_url": "https://app.example.com", // Optional - Include in invitation email
  "organization_id": "650e8400-e29b-41d4-..."   // Optional - Assign to organization (omit for external users)
}

Request Body (Public Signup)

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "username": "johndoe",                       // Optional
  "first_name": "John",                        // Optional
  "last_name": "Doe",                          // Optional
  "phone": "+1234567890"                       // Optional
}

Service Account Request Headers

Authorization: Bearer <access_token_with_write_scope>
Content-Type: application/json

Field Descriptions

send_invitation - If true, sends an invitation email with a 24-hour activation link. User can set their password via the link. Only works for service account provisioning.
default_group_id - UUID of a group in the same customer. User will be added to this group immediately after creation.
application_url - Application URL to include in the invitation email (e.g., "Click here to access YourApp"). Useful for SaaS applications.
organization_id - UUID of an organization in the same customer. If provided, user is an organization member. If omitted, user is external to all organizations.

Success Response (201 Created)

{
  "success": true,
  "user": {
    "id": "user_67890",
    "email": "[email protected]",
    "username": "jsmith",
    "first_name": "Jane",
    "last_name": "Smith",
    "email_verified": false,
    "is_active": true,
    "mfa_enabled": false,
    "created_at": "2025-01-15T12:30:00Z",
    "company_id": "customer_uuid"
  },
  "message": "User created successfully"
}

⚠️ Important Notes

  • Service account provisioned users receive a random password (not the one in the request)
  • Invitation emails contain a 24-hour activation link to set the password
  • Both default_group_id and organization_id must belong to the same customer
  • Public signup requires the signup feature flag to be enabled
  • Email verification is automatic for public signup, optional (via invitation) for service accounts
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