> ## 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 Accounts API — Manage Administrator Accounts

> Create, list, and manage admin accounts. Requires SUPER_ADMIN role. Use this endpoint to invite new administrators or revoke admin access.

The Admin Accounts API lets you manage the administrator layer of your platform — the accounts that have elevated access to customer data, inventory, orders, and analytics. You can list all admin and super\_admin accounts, view their activity details, and suspend or reactivate individual accounts. Every action here requires the SUPER\_ADMIN role; regular ADMIN accounts cannot access these endpoints.

<Warning>
  **All endpoints in this group require SUPER\_ADMIN role.** Requests from ADMIN-level sessions will receive a `403 Forbidden` response. Authenticate as a SUPER\_ADMIN before making any call to `/admin/admins`.
</Warning>

<Note>
  The platform uses three role tiers:

  * **CUSTOMER** — standard storefront access; can browse, cart, order, and review.
  * **ADMIN** — elevated access to manage products, orders, inventory, reviews, coupons, users, and view dashboard stats.
  * **SUPER\_ADMIN** — full access including role management, analytics, P\&L reports, expenses, audit logs, and admin account management. SUPER\_ADMIN role can only be assigned via the CLI.

  Use `PATCH /admin/users/{user_public_id}/role` to promote a CUSTOMER to ADMIN. You cannot assign or remove the SUPER\_ADMIN role through the API.
</Note>

***

## Authentication

All admin accounts endpoints require:

* A valid `session` cookie (obtained via `POST /auth/login`)
* SUPER\_ADMIN role
* `x-csrf-token` header on all PATCH requests

Before making any write request, call `GET /auth/csrf-token` to obtain a CSRF token:

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

***

## List Admin Accounts

Retrieve a paginated list of all accounts with ADMIN or SUPER\_ADMIN role. Each entry includes recent activity aggregates — useful for identifying inactive or stale admin accounts.

**`GET /admin/admins`**

<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 admin name or email (trimmed, max 100 characters).
</ParamField>

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

<ParamField query="activity" type="string">
  Filter by recent activity. `ACTIVE` means the admin has logged in or taken an audited action within the last 2 days. `INACTIVE` means no recent activity.
</ParamField>

<ParamField query="sort" type="string" default="-last_login_at">
  Sort field. Options: `name`, `-name`, `created_at`, `-created_at`, `last_login_at`, `-last_login_at`.
</ParamField>

<CodeGroup>
  ```bash List All Admins theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/admins?sort=-last_login_at" \
    -H "Cookie: session=<your-super-admin-session>"
  ```

  ```bash Find Inactive Admins theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/admins?activity=INACTIVE&status=ACTIVE" \
    -H "Cookie: session=<your-super-admin-session>"
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "public_id": "usr_01H",
      "first_name": "Alex",
      "last_name": "Chen",
      "email": "alex@example.com",
      "role": "ADMIN",
      "status": "ACTIVE",
      "last_login_at": "2024-06-12T08:00:00.000Z",
      "created_at": "2024-01-15T00:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

***

## Create Admin Account

Promote an existing customer to ADMIN by updating their role through the user role endpoint. To create a brand new admin account, first register a standard account via `POST /auth/register`, then call `PATCH /admin/users/{user_public_id}/role` to assign the ADMIN role.

<Steps>
  <Step title="Register the account">
    Create a new user account or locate an existing one using `GET /admin/users?search=email@example.com`.
  </Step>

  <Step title="Get the CSRF token">
    Call `GET /auth/csrf-token` with your SUPER\_ADMIN session to obtain a token.
  </Step>

  <Step title="Assign the ADMIN role">
    Call `PATCH /admin/users/{user_public_id}/role` with `{"role": "ADMIN"}` to grant admin access.
  </Step>
</Steps>

<CodeGroup>
  ```bash Register New Account theme={null}
  curl -X POST "https://api.example.com/api/v1/auth/register" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "Alex",
      "last_name": "Chen",
      "phone_number": "+14155550100",
      "email": "alex@example.com",
      "password": "S3cure!Admin"
    }'
  ```

  ```bash Promote to Admin theme={null}
  CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
    -H "Cookie: session=<your-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=<your-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": "alex@example.com",
    "role": "ADMIN"
  }
}
```

***

## Get Admin Detail

Retrieve detailed information for a single admin account, including their recent logins and audited actions. Use this to review what an admin has been doing before deciding to suspend or revoke their access.

**`GET /admin/admins/{admin_public_id}`**

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/admins/usr_01H" \
    -H "Cookie: session=<your-super-admin-session>"
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex@example.com",
    "role": "ADMIN",
    "status": "ACTIVE",
    "last_login_at": "2024-06-12T08:00:00.000Z",
    "created_at": "2024-01-15T00:00:00.000Z"
  }
}
```

***

## Suspend Admin Account

Prevent an admin from logging in by suspending their account. All active sessions for the admin are revoked immediately. Use this when access needs to be revoked quickly — for example, when an admin leaves the organisation.

**`PATCH /admin/admins/{admin_public_id}/suspend`**

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

<CodeGroup>
  ```bash Suspend Admin theme={null}
  CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
    -H "Cookie: session=<your-super-admin-session>" \
    | jq -r '.data.csrf_token')

  curl -X PATCH "https://api.example.com/api/v1/admin/admins/usr_01H/suspend" \
    -H "Cookie: session=<your-super-admin-session>" \
    -H "x-csrf-token: $CSRF"
  ```

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

  curl -X PATCH "https://api.example.com/api/v1/admin/admins/usr_01H/activate" \
    -H "Cookie: session=<your-super-admin-session>" \
    -H "x-csrf-token: $CSRF"
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "email": "alex@example.com",
    "status": "SUSPENDED"
  }
}
```

| Status Code | Meaning                                      |
| ----------- | -------------------------------------------- |
| `200`       | Account suspended or activated successfully. |
| `401`       | Missing or expired session.                  |
| `403`       | Caller is not SUPER\_ADMIN.                  |
| `404`       | Admin account not found.                     |
| `409`       | Account is already in the target state.      |

***

## Remove Admin Access

To revoke admin access without deleting the account, demote the admin back to the CUSTOMER role using `PATCH /admin/users/{user_public_id}/role` with `{"role": "CUSTOMER"}`. This preserves the account and its history while removing all admin capabilities.

<CodeGroup>
  ```bash Revoke Admin Access theme={null}
  CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
    -H "Cookie: session=<your-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=<your-super-admin-session>" \
    -H "x-csrf-token: $CSRF" \
    -H "Content-Type: application/json" \
    -d '{"role": "CUSTOMER"}'
  ```
</CodeGroup>

***

## Endpoint Summary

<CardGroup cols={2}>
  <Card title="GET /admin/admins" icon="users-gear">
    List all admin and super\_admin accounts with activity filters and sorting.
  </Card>

  <Card title="GET /admin/admins/:id" icon="user-gear">
    Retrieve detailed activity history for a single admin account.
  </Card>

  <Card title="PATCH /admin/admins/:id/suspend" icon="ban">
    Suspend an admin account, revoking all active sessions immediately.
  </Card>

  <Card title="PATCH /admin/admins/:id/activate" icon="check">
    Reactivate a suspended admin account and restore login capability.
  </Card>

  <Card title="PATCH /admin/users/:id/role" icon="shield-plus">
    Promote a CUSTOMER to ADMIN, or demote an ADMIN to CUSTOMER.
  </Card>
</CardGroup>