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

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

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

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

<CardGroup cols={3}>
  <Card title="CUSTOMER" icon="user">
    Browse the catalog, manage your cart, place and track orders, write reviews, and update your profile and addresses.
  </Card>

  <Card title="ADMIN" icon="shield-halved">
    Everything a CUSTOMER can do, plus full control over the product catalog, orders, customer accounts, review moderation, coupons, and dashboard statistics.
  </Card>

  <Card title="SUPER_ADMIN" icon="crown">
    Everything an ADMIN can do, plus role assignment, P\&L reporting, coupon analytics, operating expenses, audit log access, and management of other admin accounts.
  </Card>
</CardGroup>

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

```bash theme={null}
curl https://api.example.com/api/v1/users/me \
  --cookie "session=<your-session-cookie>"
```

**Response:**

```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
  }
}
```

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

## Permission Errors

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

<Accordion title="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.

  ```json theme={null}
  {
    "success": false,
    "message": "Authentication required.",
    "requestId": "req_01H"
  }
  ```
</Accordion>

<Accordion title="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.

  ```json theme={null}
  {
    "success": false,
    "message": "Forbidden. Insufficient permissions.",
    "requestId": "req_02H"
  }
  ```
</Accordion>

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