> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Users API — Search, Update, and Manage Accounts

> List and manage customer accounts, update contact details, suspend or reactivate accounts, and change user roles. Requires ADMIN role.

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.

<Note>
  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.
</Note>

***

## 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`**

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Items per page. Minimum 1, maximum 100.
</ParamField>

<ParamField query="search" type="string">
  Free-text search against name and email fields (trimmed, max 100 characters).
</ParamField>

<ParamField query="status" type="string">
  Filter by account status. One of `ACTIVE`, `SUSPENDED`, or `DELETED`.
</ParamField>

<ParamField query="include_deleted" type="string" default="false">
  Set to `"true"` to include soft-deleted accounts in results.
</ParamField>

<ParamField query="sort" type="string" default="-created_at">
  Sort field. Prefix with `-` for descending order. Options: `name`, `-name`, `email`, `-email`, `created_at`, `-created_at`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  # 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>"
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "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}`**

<ParamField path="user_public_id" type="string" required>
  The user's public ID (prefix: `usr_`).
</ParamField>

**Response `200 OK`**

```json theme={null}
{
  "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}`**

<ParamField path="user_public_id" type="string" required>
  The user's public ID (prefix: `usr_`).
</ParamField>

<ParamField body="first_name" type="string">
  Updated first name. 1–100 characters.
</ParamField>

<ParamField body="last_name" type="string">
  Updated last name. 1–100 characters.
</ParamField>

<ParamField body="email" type="string">
  Updated email address. Triggers reverification. Must be unique.
</ParamField>

<ParamField body="phone_number" type="string">
  Updated phone number in E.164 format (e.g. `+14155552671`). Triggers reverification.
</ParamField>

<Warning>
  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.
</Warning>

<CodeGroup>
  ```bash Update Name theme={null}
  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"}'
  ```
</CodeGroup>

**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.

<Warning>
  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.
</Warning>

<CodeGroup>
  ```bash Suspend User theme={null}
  # 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"
  ```

  ```bash Reactivate User theme={null}
  # 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"
  ```
</CodeGroup>

**Response `200 OK` (suspend or activate)**

```json theme={null}
{
  "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`**

<Note>
  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.
</Note>

<ParamField path="user_public_id" type="string" required>
  The user's public ID (prefix: `usr_`).
</ParamField>

<ParamField body="role" type="string" required>
  The new role for the user. Must be `"CUSTOMER"` or `"ADMIN"`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="GET /admin/users" icon="users">
    List all customer accounts with filtering, search, and pagination.
  </Card>

  <Card title="GET /admin/users/:id" icon="user">
    Retrieve a single user's full profile by public ID.
  </Card>

  <Card title="PATCH /admin/users/:id" icon="pen">
    Update a user's contact details. Triggers reverification for email or phone changes.
  </Card>

  <Card title="PATCH /admin/users/:id/role" icon="shield">
    Promote or demote a user's role. Requires SUPER\_ADMIN.
  </Card>

  <Card title="PATCH /admin/users/:id/suspend" icon="ban">
    Suspend an account and revoke all active sessions immediately.
  </Card>

  <Card title="PATCH /admin/users/:id/activate" icon="check">
    Restore a suspended account and re-enable login.
  </Card>
</CardGroup>