Admin Accounts API — Manage Administrator Accounts

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.

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.

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.

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:

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

integer

default:"1"

Page number (1-based).

integer

default:"20"

Items per page. Minimum 1, maximum 100.

string

Free-text search against admin name or email (trimmed, max 100 characters).

string

Filter by account status. One of ACTIVE or SUSPENDED.

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.

string

default:"-last_login_at"

Sort field. Options: name, -name, created_at, -created_at, last_login_at, -last_login_at.

curl -X GET "https://api.example.com/api/v1/admin/admins?sort=-last_login_at" \
  -H "Cookie: session=<your-super-admin-session>"

curl -X GET "https://api.example.com/api/v1/admin/admins?activity=INACTIVE&status=ACTIVE" \
  -H "Cookie: session=<your-super-admin-session>"

Response 200 OK

{
  "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.

Create a new user account or locate an existing one using GET /admin/users?search=email@example.com.

Get the CSRF token

Call GET /auth/csrf-token with your SUPER_ADMIN session to obtain a token.

Assign the ADMIN role

Call PATCH /admin/users/{user_public_id}/role with {"role": "ADMIN"} to grant admin access.

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"
  }'

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"}'

Response 200 OK

{
  "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}

string

required

The admin account’s public ID (prefix: usr_).

curl -X GET "https://api.example.com/api/v1/admin/admins/usr_01H" \
  -H "Cookie: session=<your-super-admin-session>"

Response 200 OK

{
  "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

string

required

The admin account’s public ID (prefix: usr_).

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"

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"

Response 200 OK

{
  "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.

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"}'

Endpoint Summary

GET /admin/admins

List all admin and super_admin accounts with activity filters and sorting.

GET /admin/admins/:id

Retrieve detailed activity history for a single admin account.

PATCH /admin/admins/:id/suspend

Suspend an admin account, revoking all active sessions immediately.

PATCH /admin/admins/:id/activate

Reactivate a suspended admin account and restore login capability.

PATCH /admin/users/:id/role

Promote a CUSTOMER to ADMIN, or demote an ADMIN to CUSTOMER.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Accounts API — Manage Administrator Accounts

Authentication

List Admin Accounts

Create Admin Account

Get Admin Detail

Suspend Admin Account

Remove Admin Access

Endpoint Summary

GET /admin/admins

GET /admin/admins/:id

PATCH /admin/admins/:id/suspend

PATCH /admin/admins/:id/activate

PATCH /admin/users/:id/role

​Authentication

​List Admin Accounts

​Create Admin Account

​Get Admin Detail

​Suspend Admin Account

​Remove Admin Access

​Endpoint Summary

GET /admin/admins

GET /admin/admins/:id

PATCH /admin/admins/:id/suspend

PATCH /admin/admins/:id/activate

PATCH /admin/users/:id/role

Authentication

List Admin Accounts

Create Admin Account

Get Admin Detail

Suspend Admin Account

Remove Admin Access

Endpoint Summary