Admin Users API — Search, Update, and Manage Accounts

The Admin Users API gives you full visibility into every customer account on the platform. Use it to search for users by name or email, inspect individual profiles, update contact details, suspend or reactivate accounts, and — if you hold the SUPER_ADMIN role — promote or demote user roles. All endpoints require an active admin session with at least the ADMIN role; role changes are restricted to SUPER_ADMIN only.

Before making any write request, call GET /auth/csrf-token to obtain a CSRF token and include it in the x-csrf-token header alongside your session cookie.

Authentication

All admin user endpoints require:

A valid session cookie (obtained via POST /auth/login)
ADMIN or SUPER_ADMIN role
x-csrf-token header on all PATCH requests

List Customers

Retrieve a paginated list of user accounts. You can filter by account status, search by name or email, include soft-deleted accounts, and sort by name, email, or creation date. GET /admin/users

integer

default:"1"

Page number (1-based).

integer

default:"20"

Items per page. Minimum 1, maximum 100.

string

Free-text search against name and email fields (trimmed, max 100 characters).

string

Filter by account status. One of ACTIVE, SUSPENDED, or DELETED.

string

default:"false"

Set to "true" to include soft-deleted accounts in results.

string

default:"-created_at"

Sort field. Prefix with - for descending order. Options: name, -name, email, -email, created_at, -created_at.

# Step 1: get CSRF token
CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-token>" \
  | jq -r '.data.csrf_token')

# Step 2: list users
curl -X GET "https://api.example.com/api/v1/admin/users?page=1&limit=20&status=ACTIVE" \
  -H "Cookie: session=<your-session-token>"

Response 200 OK

{
  "success": true,
  "data": [
    {
      "public_id": "usr_01H",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone_number": "+14155552671",
      "role": "CUSTOMER",
      "email_verified": true,
      "created_at": "2024-03-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

Get User Detail

Fetch the full profile for a specific user account by their public ID. GET /admin/users/{user_public_id}

string

required

The user’s public ID (prefix: usr_).

Response 200 OK

{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone_number": "+14155552671",
    "role": "CUSTOMER",
    "email_verified": true,
    "created_at": "2024-03-01T10:00:00.000Z",
    "updated_at": "2024-04-15T08:30:00.000Z"
  }
}

Update User

Update a customer’s contact details. You can update first name, last name, email, and phone number. Changing email or phone triggers reverification for the affected field and creates an audit entry. Supply at least one field. PATCH /admin/users/{user_public_id}

string

required

The user’s public ID (prefix: usr_).

string

Updated first name. 1–100 characters.

string

Updated last name. 1–100 characters.

string

Updated email address. Triggers reverification. Must be unique.

string

Updated phone number in E.164 format (e.g. +14155552671). Triggers reverification.

Updating a customer’s email address will mark their email as unverified and send a new verification link to the new address. The account remains accessible but the email_verified flag resets to false until they confirm.

CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-token>" \
  | jq -r '.data.csrf_token')

curl -X PATCH "https://api.example.com/api/v1/admin/users/usr_01H" \
  -H "Cookie: session=<your-session-token>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane", "last_name": "Smith"}'

Suspend a User Account Use PATCH /admin/users/{user_public_id}/suspend to immediately prevent a user from logging in. All active sessions are revoked upon suspension.

Suspended accounts cannot log in. Existing sessions are revoked immediately when you suspend an account. Use PATCH /admin/users/{user_public_id}/activate to restore access.

# Step 1: get CSRF token
CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-token>" \
  | jq -r '.data.csrf_token')

# Step 2: suspend the account
curl -X PATCH "https://api.example.com/api/v1/admin/users/usr_01H/suspend" \
  -H "Cookie: session=<your-session-token>" \
  -H "x-csrf-token: $CSRF"

# Step 1: get CSRF token
CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-token>" \
  | jq -r '.data.csrf_token')

# Step 2: reactivate the account
curl -X PATCH "https://api.example.com/api/v1/admin/users/usr_01H/activate" \
  -H "Cookie: session=<your-session-token>" \
  -H "x-csrf-token: $CSRF"

Response 200 OK (suspend or activate)

{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "email": "jane@example.com",
    "status": "SUSPENDED"
  }
}

Status Code	Meaning
`200`	Account suspended or activated successfully.
`401`	Missing or expired session.
`403`	Insufficient role.
`404`	User not found.
`409`	Account is already in the target state.

Change User Role

Promote a customer to ADMIN, or demote an admin back to CUSTOMER. You cannot change a SUPER_ADMIN’s role via the API — that operation is CLI-only. PATCH /admin/users/{user_public_id}/role

Role changes require the SUPER_ADMIN role. ADMIN-level sessions will receive a 403 Forbidden response. SUPER_ADMIN accounts cannot be modified through this endpoint; use the CLI for that operation.

string

required

The user’s public ID (prefix: usr_).

string

required

The new role for the user. Must be "CUSTOMER" or "ADMIN".

CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<super-admin-session>" \
  | jq -r '.data.csrf_token')

curl -X PATCH "https://api.example.com/api/v1/admin/users/usr_01H/role" \
  -H "Cookie: session=<super-admin-session>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{"role": "ADMIN"}'

Response 200 OK

{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "email": "jane@example.com",
    "role": "ADMIN"
  }
}

Status Code	Meaning
`200`	Role updated successfully.
`400`	Invalid role value.
`401`	Missing or expired session.
`403`	Caller is not SUPER_ADMIN, or target is SUPER_ADMIN.
`404`	User not found.

Endpoint Summary

GET /admin/users

List all customer accounts with filtering, search, and pagination.

GET /admin/users/:id

Retrieve a single user’s full profile by public ID.

PATCH /admin/users/:id

Update a user’s contact details. Triggers reverification for email or phone changes.

PATCH /admin/users/:id/role

Promote or demote a user’s role. Requires SUPER_ADMIN.

PATCH /admin/users/:id/suspend

Suspend an account and revoke all active sessions immediately.

PATCH /admin/users/:id/activate

Restore a suspended account and re-enable login.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Users API — Search, Update, and Manage Accounts

Authentication

List Customers

Get User Detail

Update User

Change User Role

Endpoint Summary

GET /admin/users

GET /admin/users/:id

PATCH /admin/users/:id

PATCH /admin/users/:id/role

PATCH /admin/users/:id/suspend

PATCH /admin/users/:id/activate

​Authentication

​List Customers

​Get User Detail

​Update User

​Change User Role

​Endpoint Summary

GET /admin/users

GET /admin/users/:id

PATCH /admin/users/:id

PATCH /admin/users/:id/role

PATCH /admin/users/:id/suspend

PATCH /admin/users/:id/activate

Authentication

List Customers

Get User Detail

Update User

Change User Role

Endpoint Summary