Admin Users API

Manage users across the platform with administrative privileges. These endpoints allow you to list, create, update, and delete user accounts.

Base URL

/api/admin/users

Authentication

Required: Admin role

Authorization: Bearer <admin_session_token>

Endpoints

List Users

Retrieve a paginated list of all users in the system.

GET /api/admin/users

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`search`	string	-	Search by email or name
`role`	string	-	Filter by role (admin, user)
`status`	string	-	Filter by status (active, suspended, pending)
`organizationId`	string	-	Filter by organization membership

Response

{
  "success": true,
  "data": [
    {
      "id": "user_123456",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "user",
      "status": "active",
      "organizationId": "org_789",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastLoginAt": "2024-02-01T14:22:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Get User

Retrieve details for a specific user.

GET /api/admin/users/:id

Response

{
  "success": true,
  "data": {
    "id": "user_123456",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "user",
    "status": "active",
    "organizationId": "org_789",
    "organization": {
      "id": "org_789",
      "name": "Acme Corp"
    },
    "metadata": {
      "signupSource": "web",
      "referralCode": "FRIEND50"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T08:15:00Z",
    "lastLoginAt": "2024-02-01T14:22:00Z"
  }
}

Create User

Create a new user account.

POST /api/admin/users

Request Body

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "user",
  "organizationId": "org_789",
  "password": "secure-password-123",
  "sendWelcomeEmail": true
}

Request Fields

Field	Type	Required	Description
`email`	string	Yes	User's email address
`name`	string	No	User's display name
`role`	string	No	User role (default: `user`)
`organizationId`	string	No	Organization to assign user to
`password`	string	No	Initial password (auto-generated if omitted)
`sendWelcomeEmail`	boolean	No	Send welcome email (default: `false`)

Response

{
  "success": true,
  "data": {
    "id": "user_789012",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "user",
    "status": "active",
    "organizationId": "org_789",
    "createdAt": "2024-02-04T10:00:00Z"
  }
}

Update User

Update an existing user's information.

PATCH /api/admin/users/:id

Request Body

{
  "name": "Jane Doe",
  "role": "admin",
  "status": "active",
  "organizationId": "org_456"
}

Response

{
  "success": true,
  "data": {
    "id": "user_789012",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "role": "admin",
    "status": "active",
    "organizationId": "org_456",
    "updatedAt": "2024-02-04T11:30:00Z"
  }
}

Delete User

Permanently delete a user account.

DELETE /api/admin/users/:id

Query Parameters

Parameter	Type	Default	Description
`transferDataTo`	string	-	User ID to transfer data to before deletion
`deleteData`	boolean	false	Permanently delete all user data

Response

{
  "success": true,
  "data": {
    "message": "User deleted successfully",
    "deletedAt": "2024-02-04T12:00:00Z"
  }
}

Suspend User

Temporarily suspend a user account.

POST /api/admin/users/:id/suspend

Request Body

{
  "reason": "Violation of terms of service",
  "duration": "7d"
}

Response

{
  "success": true,
  "data": {
    "id": "user_123456",
    "status": "suspended",
    "suspendedUntil": "2024-02-11T12:00:00Z",
    "suspensionReason": "Violation of terms of service"
  }
}

Reactivate User

Reactivate a suspended user account.

POST /api/admin/users/:id/reactivate

Response

{
  "success": true,
  "data": {
    "id": "user_123456",
    "status": "active",
    "reactivatedAt": "2024-02-04T12:00:00Z"
  }
}

Error Codes

Code	Description
`USER_NOT_FOUND`	The specified user does not exist
`EMAIL_ALREADY_EXISTS`	Email address is already in use
`INVALID_ORGANIZATION`	Organization ID is invalid
`CANNOT_DELETE_SELF`	Admins cannot delete their own account
`CANNOT_SUSPEND_SELF`	Admins cannot suspend their own account

SDK Example

import { createAdminClient } from '@/lib/admin/client';

const admin = createAdminClient();

// List users with filters
const users = await admin.users.list({
  role: 'user',
  status: 'active',
  search: 'john',
  page: 1,
  limit: 50
});

// Create a new user
const newUser = await admin.users.create({
  email: 'newuser@example.com',
  name: 'New User',
  role: 'user',
  sendWelcomeEmail: true
});

// Update user role
await admin.users.update('user_123456', {
  role: 'admin'
});

// Suspend user
await admin.users.suspend('user_123456', {
  reason: 'Account review pending',
  duration: '3d'
});

Admin Users API

On this page