User Management API

RESTful API endpoints for managing users, roles, and permissions

All endpoints require authentication via Clerk session token. Include Authorization: Bearer <token> header in all requests.

List Users

GET /api/users

GET

Retrieve a paginated list of all users

Query Parameters

?page=1 - Page number (default: 1)

&search=john - Search by name or email

&role=MEMBER - Filter by role (MASTER_ADMIN | GROUP_ADMIN | MEMBER)

&limit=20 - Items per page (default: 20)

Example Request

GET /api/users?page=1&search=john&role=MEMBER
Authorization: Bearer <clerk-session-token>

Example Response

{
  "success": true,
  "data": [
    {
      "id": "user_123",
      "clerkId": "clerk_abc",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "MEMBER",
      "isActive": true,
      "emailVerified": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "lastLoginAt": "2024-03-20T14:25:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Permissions Required

MASTER_ADMIN - View all users

GROUP_ADMIN - View users in managed groups

Get User

GET /api/users/:id

GET

Retrieve detailed information about a specific user

Path Parameters

:id - User ID (string)

Example Response

{
  "success": true,
  "data": {
    "id": "user_123",
    "clerkId": "clerk_abc",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "MEMBER",
    "isActive": true,
    "emailVerified": true,
    "phoneNumber": "+1234567890",
    "imageUrl": "https://...",
    "groups": [
      {
        "id": "group_1",
        "name": "Engineering",
        "role": "MEMBER"
      }
    ],
    "applications": [
      {
        "id": "app_1",
        "name": "Project Manager",
        "hasAccess": true
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "lastLoginAt": "2024-03-20T14:25:00Z"
  }
}

Create User

POST /api/users

POST

Create a new user account

Request Body

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "MEMBER",  // MASTER_ADMIN | GROUP_ADMIN | MEMBER
  "phoneNumber": "+1234567890",  // Optional
  "sendInvitation": true  // Optional, sends email invite
}

Example Response

{
  "success": true,
  "data": {
    "id": "user_456",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "MEMBER",
    "isActive": true,
    "invitation": {
      "token": "inv_token_xyz",
      "expiresAt": "2024-04-01T00:00:00Z"
    }
  }
}

Permissions Required

MASTER_ADMIN only

Update User

PATCH /api/users/:id

PATCH

Update user profile and permissions

Request Body

{
  "firstName": "Jane",  // Optional
  "lastName": "Smith",  // Optional
  "role": "GROUP_ADMIN",  // Optional
  "isActive": false,  // Optional - deactivate user
  "phoneNumber": "+0987654321"  // Optional
}

Example Response

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "john.doe@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "GROUP_ADMIN",
    "isActive": false,
    "updatedAt": "2024-03-20T15:00:00Z"
  }
}

Role changes are audited. MASTER_ADMIN can change any user's role. GROUP_ADMIN can only change roles within their managed groups.

Delete User

DELETE /api/users/:id

DELETE

Soft delete a user account (deactivation)

Example Response

{
  "success": true,
  "message": "User deleted successfully",
  "data": {
    "id": "user_123",
    "isActive": false,
    "deletedAt": "2024-03-20T15:30:00Z"
  }
}

Users are soft-deleted (marked as inactive) to preserve audit trails. Hard deletion is only performed after retention period expires.

Permissions Required

MASTER_ADMIN only

Get User Statistics

GET /api/users/:id/stats

GET

Retrieve user activity statistics and metrics

Example Response

{
  "success": true,
  "data": {
    "userId": "user_123",
    "loginCount": 145,
    "lastLoginAt": "2024-03-20T14:25:00Z",
    "averageSessionDuration": 3600,  // seconds
    "groupCount": 3,
    "applicationCount": 8,
    "activeApplications": 5,
    "invitationsSent": 12,
    "invitationsAccepted": 8
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired session token"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to perform this action"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

Best Practices

• Use pagination for large user lists

• Validate email format before creating users

• Send invitations when creating new users

• Check permissions before role changes

• Use search filters to reduce response size

Don't

• Fetch all users without pagination

• Hard delete users (use soft delete)

• Change roles without audit logging

• Skip email verification checks

• Expose sensitive user data unnecessarily

User Management API

RESTful API endpoints for managing users, roles, and permissions

All endpoints require authentication via Clerk session token. Include Authorization: Bearer <token> header in all requests.

List Users

GET /api/users

GET

Retrieve a paginated list of all users

Query Parameters

?page=1 - Page number (default: 1)

&search=john - Search by name or email

&role=MEMBER - Filter by role (MASTER_ADMIN | GROUP_ADMIN | MEMBER)

&limit=20 - Items per page (default: 20)

Example Request

GET /api/users?page=1&search=john&role=MEMBER
Authorization: Bearer <clerk-session-token>

Example Response

{
  "success": true,
  "data": [
    {
      "id": "user_123",
      "clerkId": "clerk_abc",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "MEMBER",
      "isActive": true,
      "emailVerified": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "lastLoginAt": "2024-03-20T14:25:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Permissions Required

MASTER_ADMIN - View all users

GROUP_ADMIN - View users in managed groups

Get User

GET /api/users/:id

GET

Retrieve detailed information about a specific user

Path Parameters

:id - User ID (string)

Example Response

{
  "success": true,
  "data": {
    "id": "user_123",
    "clerkId": "clerk_abc",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "MEMBER",
    "isActive": true,
    "emailVerified": true,
    "phoneNumber": "+1234567890",
    "imageUrl": "https://...",
    "groups": [
      {
        "id": "group_1",
        "name": "Engineering",
        "role": "MEMBER"
      }
    ],
    "applications": [
      {
        "id": "app_1",
        "name": "Project Manager",
        "hasAccess": true
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "lastLoginAt": "2024-03-20T14:25:00Z"
  }
}

Create User

POST /api/users

POST

Create a new user account

Request Body

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "MEMBER",  // MASTER_ADMIN | GROUP_ADMIN | MEMBER
  "phoneNumber": "+1234567890",  // Optional
  "sendInvitation": true  // Optional, sends email invite
}

Example Response

{
  "success": true,
  "data": {
    "id": "user_456",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "MEMBER",
    "isActive": true,
    "invitation": {
      "token": "inv_token_xyz",
      "expiresAt": "2024-04-01T00:00:00Z"
    }
  }
}

Permissions Required

MASTER_ADMIN only

Update User

PATCH /api/users/:id

PATCH

Update user profile and permissions

Request Body

{
  "firstName": "Jane",  // Optional
  "lastName": "Smith",  // Optional
  "role": "GROUP_ADMIN",  // Optional
  "isActive": false,  // Optional - deactivate user
  "phoneNumber": "+0987654321"  // Optional
}

Example Response

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "john.doe@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "GROUP_ADMIN",
    "isActive": false,
    "updatedAt": "2024-03-20T15:00:00Z"
  }
}

Role changes are audited. MASTER_ADMIN can change any user's role. GROUP_ADMIN can only change roles within their managed groups.

Delete User

DELETE /api/users/:id

DELETE

Soft delete a user account (deactivation)

Example Response

{
  "success": true,
  "message": "User deleted successfully",
  "data": {
    "id": "user_123",
    "isActive": false,
    "deletedAt": "2024-03-20T15:30:00Z"
  }
}

Users are soft-deleted (marked as inactive) to preserve audit trails. Hard deletion is only performed after retention period expires.

Permissions Required

MASTER_ADMIN only

Get User Statistics

GET /api/users/:id/stats

GET

Retrieve user activity statistics and metrics

Example Response

{
  "success": true,
  "data": {
    "userId": "user_123",
    "loginCount": 145,
    "lastLoginAt": "2024-03-20T14:25:00Z",
    "averageSessionDuration": 3600,  // seconds
    "groupCount": 3,
    "applicationCount": 8,
    "activeApplications": 5,
    "invitationsSent": 12,
    "invitationsAccepted": 8
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired session token"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to perform this action"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

Best Practices

• Use pagination for large user lists

• Validate email format before creating users

• Send invitations when creating new users

• Check permissions before role changes

• Use search filters to reduce response size

Don't

• Fetch all users without pagination

• Hard delete users (use soft delete)

• Change roles without audit logging

• Skip email verification checks

• Expose sensitive user data unnecessarily

User Management API

List Users

Query Parameters

Example Request

Example Response

Permissions Required

Get User

Path Parameters

Example Response

Create User

Request Body

Example Response

Permissions Required

Update User

Request Body

Example Response

Delete User

Example Response

Permissions Required

Get User Statistics

Example Response

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Best Practices

See Also

User Management API

List Users

Query Parameters

Example Request

Example Response

Permissions Required

Get User

Path Parameters

Example Response

Create User

Request Body

Example Response

Permissions Required

Update User

Request Body

Example Response

Delete User

Example Response

Permissions Required

Get User Statistics

Example Response

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Best Practices

See Also