Autenticazione

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 sugli endpoint /admin/* viene rifiutata (403 api_key.admin_route_forbidden). 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 o revocata dal gestore. Chiave errata o revocata: 401 api_key.invalid; origin non ammessa: 403 api_key.origin_not_allowed.

2. Sessione cliente: account dello shopper

Authorization: Bearer <access_token>

Refresh a rotazione

curl -X POST "$BASE/api/v1/auth/refresh" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<refresh_token salvato>"}'

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
  },
  "meta": null,
  "error": null,
  "error_code": null
}

1. Su un 401 di una chiamata qualsiasi, chiama POST /auth/refresh, salva la coppia nuova e ripeti la richiesta.
2. Fai un solo refresh alla volta: le richieste che ricevono 401 nello stesso momento aspettano lo stesso rinnovo.
3. Su 401 da /auth/refresh (auth.session_revoked, auth.refresh_token_reused, auth.refresh_token_invalid) o su 403 auth.tenant_unavailable, cancella i token e porta l’utente al login.
4. Su errori di rete o 5xx non buttare la sessione: riprova più tardi.

Logout

• POST /auth/logout con {"refresh_token": "..."} nel corpo chiude questa sessione: da quel momento quel refresh token risponde 401 auth.session_revoked. È idempotente e non richiede l’access token. L’access token vale fino alla sua scadenza: buttalo nel client.
• POST /auth/logout?all=true chiude tutte le sessioni dell’account, su ogni dispositivo («esci da tutti i dispositivi»). Serve una credenziale valida: l’header Authorization: Bearer <access_token>, oppure il refresh token nel corpo se l’access token è già scaduto. Senza: 401 auth.not_authenticated.

# esci da tutti i dispositivi
curl -X POST "$BASE/api/v1/auth/logout?all=true" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "Authorization: Bearer $TOKEN"

Verifica in due passaggi (2FA)

1. Attivazione: POST /auth/2fa/setup con {"current_password": "..."} restituisce secret e qr_uri da mostrare come QR code. Poi POST /auth/2fa/verify con {"code": "123456", "current_password": "..."} attiva la 2FA, chiude le altre sessioni e risponde con i token nuovi più 10 codici di recupero (recovery_codes).
2. Codici di recupero: hanno la forma xxxxx-xxxxx, valgono una volta e vanno mostrati all’utente una sola volta, alla risposta di attivazione. Ognuno sostituisce il codice dell’app al login e per disattivare la 2FA.
3. Login: con la 2FA attiva il primo POST /auth/login risponde 401 auth.totp_required. Ripeti la stessa chiamata con totp_code, che accetta il codice dell’app oppure un codice di recupero. Ogni codice TOTP vale una volta sola: lo stesso codice ripresentato dà 401 auth.totp_invalid.
4. Rigenerazione: POST /auth/2fa/recovery-codes con {"current_password": "..."} restituisce 10 codici nuovi; i vecchi smettono di valere. GET /auth/me espone recovery_codes_remaining (null con la 2FA spenta): quando scende vicino a 0, invita l’utente a rigenerarli.
5. Disattivazione: POST /auth/2fa/disable con {"code": "..."} (codice dell’app o di recupero). Chiude le altre sessioni, azzera i codici di recupero e restituisce i token nuovi.

{
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "token_type": "bearer",
    "recovery_codes": ["k3m7p-xq2rt", "…10 codici in tutto…"]
  },
  "meta": null,
  "error": null,
  "error_code": null
}

Negozio eliminato

• POST /auth/login (con la password giusta) e POST /auth/refresh rispondono 403 auth.tenant_unavailable;
• ogni altra chiamata autenticata con un token di quel negozio risponde 401 auth.tenant_unavailable.

3. Token staff: Admin API

Authorization: Bearer <staff_access_token>

• Il login è lo stesso POST /auth/login, con le credenziali di un utente staff. Valgono le stesse regole di rotazione, con la regola stretta sul riuso descritta sopra.
• Il token porta il claim tenant_id: ogni sessione è vincolata al suo negozio (isolamento multi-tenant a prova di leak).
• Per automazioni e agenti che lavorano a lungo c’è il token API: si usa come Bearer, senza login né refresh, con una scadenza obbligatoria. Vedi Gestisci il negozio via API.
• Le mutazioni admin sono audit-loggate.
• Le chiavi publishable non danno mai accesso qui.

Codici di errore auth comuni