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

# Authentication

> Publishable key, customer session, and staff token — when to use which.

Vellaro has three levels of credentials, with clear boundaries.

## 1. Publishable key — identifies the store

```
X-Vellaro-Key: cx_pk_live_<slug>_XXXXXXXXXXXXXXXXXXXXXXXX
```

* **What it does**: tells the API *which store*. Like Stripe's publishable keys, it can live
  in the client (web/mobile).
* **What it does NOT do**: it does not authenticate a user and is **rejected** on `/admin/*` and
  `/super-admin/*`. The blast radius of a leaked key is limited to the storefront.
* **Format**: `cx_pk_<live|test>_<slug>_<random>`. Use `test` only in development.
* It can have origin restrictions and can be rotated/revoked by the operator.

<Tip>
  If your calls originate from the **store's domain**, the key is optional: the store
  is resolved from the domain. It's needed for mobile apps and server-side clients without a domain.
</Tip>

## 2. Customer session — shopper account

For account areas (orders, addresses, wishlist, subscriptions) the customer logs in and gets
a token:

```
Authorization: Bearer <access_token>
```

| Token           | Lifetime | Use                                                        |
| --------------- | -------- | ---------------------------------------------------------- |
| `access_token`  | \~30 min | `Authorization: Bearer` header on every authenticated call |
| `refresh_token` | long     | refreshes the access token via `POST /auth/refresh`        |

Registration/login: `POST /auth/register`, `POST /auth/login` (with 2FA if enabled),
`POST /auth/refresh`, Google OAuth. See the [API Reference](/en/api-reference).

## 3. Staff token — Admin API

The `/admin/*` endpoints require a **staff account** (JWT) with the right **permissions**
(catalog, sales, customers, content, marketing, reports, tax, users, system…).

```
Authorization: Bearer <staff_access_token>
```

* The token carries the `tenant_id` claim: every session is bound to **its** store
  (leak-proof multi-tenant isolation).
* Admin mutations are **audit-logged**.
* Publishable keys never grant access here.

<Warning>
  Never embed a staff token in a public client (web/mobile). The Admin API is for
  backends, server-side integrations, and automations (including the [admin MCP](/en/ai-mcp)).
</Warning>

## Common auth error codes

| `error_code`               | Meaning                                     |
| -------------------------- | ------------------------------------------- |
| `auth.not_authenticated`   | `Authorization` header missing              |
| `auth.invalid_credentials` | wrong email/password                        |
| `auth.totp_required`       | 2FA enabled: repeat the login with the code |
| `auth.forbidden`           | the role lacks the required permission      |