Roles and Permissions: CUSTOMER, ADMIN, and SUPER_ADMIN

The Ecommerce API has three user roles — CUSTOMER, ADMIN, and SUPER_ADMIN — each with different access to storefront and admin endpoints.

The Ecommerce API uses a three-tier role system to control access across the platform. Every authenticated account carries exactly one role — CUSTOMER, ADMIN, or SUPER_ADMIN — and that role determines which endpoints you can call. Storefront endpoints are available to all authenticated users; admin endpoints require at least ADMIN; and sensitive operations such as role assignment, P&L reporting, coupon analytics, and the audit log require SUPER_ADMIN. Public catalog and category browsing requires no authentication at all.

Every new account created via POST /auth/register starts with the CUSTOMER role. Elevation to ADMIN or SUPER_ADMIN must be performed by an existing SUPER_ADMIN account.

Role Overview

Role	Access
CUSTOMER	Storefront endpoints: product and category catalog, cart management, checkout and order history, product reviews, own profile and address book
ADMIN	All CUSTOMER access, plus: admin catalog management (products, variants, images, categories, inventory), order queue and status transitions, customer user management, review moderation, coupon lifecycle management, and dashboard statistics
SUPER_ADMIN	All ADMIN access, plus: user role assignment, P&L reporting, coupon analytics, operating expense management, append-only audit log, and admin account administration

CUSTOMER

Browse the catalog, manage your cart, place and track orders, write reviews, and update your profile and addresses.

ADMIN

Everything a CUSTOMER can do, plus full control over the product catalog, orders, customer accounts, review moderation, coupons, and dashboard statistics.

SUPER_ADMIN

Everything an ADMIN can do, plus role assignment, P&L reporting, coupon analytics, operating expenses, audit log access, and management of other admin accounts.

Checking Your Role

To check the role of the currently authenticated user, call GET /users/me. The response includes a role field in the data object.

curl https://api.example.com/api/v1/users/me \
  --cookie "session=<your-session-cookie>"

Response:

{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]",
    "role": "CUSTOMER",
    "email_verified": true
  }
}

The role field is present in the responses of both GET /auth/session and GET /users/me. Use GET /auth/session for a lightweight check when you only need the session state and role without the full profile.

Permission Errors

When an API call fails due to access control, the response status code tells you exactly why:

401 Unauthorized — Not Authenticated

The request reached a protected endpoint without a valid session cookie. This happens when:

• No session cookie was sent
• The session has expired or been revoked (e.g. after DELETE /auth/session or a password change)

Resolution: Call POST /auth/login to obtain a new session, then retry the request with the new cookie.

{
  "success": false,
  "message": "Authentication required.",
  "requestId": "req_01H"
}

403 Forbidden — Insufficient Role

The request was made with a valid session, but the authenticated account’s role does not have permission to access the endpoint. For example, a CUSTOMER calling an admin endpoint or an ADMIN calling a SUPER_ADMIN-only endpoint.

Resolution: Use an account with the required role, or contact a SUPER_ADMIN to elevate your role if appropriate.

{
  "success": false,
  "message": "Forbidden. Insufficient permissions.",
  "requestId": "req_02H"
}

Do not confuse 401 and 403. A 401 means the API does not know who you are — you need to log in. A 403 means the API knows exactly who you are but your role is not permitted to perform that action. Retrying a 403 response with the same credentials will always fail.