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

# Autenticazione

> Chiave publishable, sessione cliente e token staff — quando usare cosa.

Vellaro ha tre livelli di credenziali, con confini netti.

## 1. Chiave publishable — identifica il negozio

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

* **Cosa fa**: dice all'API *quale negozio*. Come le chiavi pubbliche di Stripe, può stare
  nel client (web/mobile).
* **Cosa NON fa**: non autentica un utente e viene **rifiutata** su `/admin/*` e
  `/super-admin/*`. Il raggio d'azione di una chiave trapelata è limitato allo storefront.
* **Formato**: `cx_pk_<live|test>_<slug>_<random>`. Usa `test` solo in sviluppo.
* Può avere restrizioni di origin e può essere ruotata/revocata dal gestore.

<Tip>
  Se le tue chiamate partono dal **dominio del negozio**, la chiave è opzionale: il negozio
  è risolto dal dominio. Serve per app mobile e client server-side senza dominio.
</Tip>

## 2. Sessione cliente — account dello shopper

Per le aree account (ordini, indirizzi, wishlist, abbonamenti) il cliente fa login e ottiene
un token:

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

| Token           | Durata   | Uso                                                         |
| --------------- | -------- | ----------------------------------------------------------- |
| `access_token`  | \~30 min | header `Authorization: Bearer` su ogni chiamata autenticata |
| `refresh_token` | lunga    | rinnova l'access token via `POST /auth/refresh`             |

Registrazione/login: `POST /auth/register`, `POST /auth/login` (con 2FA se attiva),
`POST /auth/refresh`, Google OAuth. Vedi la [API Reference](/api-reference).

## 3. Token staff — Admin API

Gli endpoint `/admin/*` richiedono un **account staff** (JWT) con i **permessi** giusti
(catalog, sales, customers, content, marketing, reports, tax, users, system…).

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

* Il token porta il claim `tenant_id`: ogni sessione è vincolata al **suo** negozio
  (isolamento multi-tenant a prova di leak).
* Le mutazioni admin sono **audit-loggate**.
* Le chiavi publishable non danno mai accesso qui.

<Warning>
  Non incorporare mai un token staff in un client pubblico (web/mobile). La Admin API è per
  backend, integrazioni server-side e automazioni (incluso l'[MCP admin](/ai-mcp)).
</Warning>

## Codici di errore auth comuni

| `error_code`               | Significato                            |
| -------------------------- | -------------------------------------- |
| `auth.not_authenticated`   | header `Authorization` assente         |
| `auth.invalid_credentials` | email/password errati                  |
| `auth.totp_required`       | 2FA attiva: ripeti il login col codice |
| `auth.forbidden`           | il ruolo non ha il permesso richiesto  |