Authentication

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 the /admin/* endpoints (403 api_key.admin_route_forbidden). 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 or revoked by the operator. A wrong or revoked key: 401 api_key.invalid; an origin that is not allowed: 403 api_key.origin_not_allowed.

2. Customer session: shopper account

Authorization: Bearer <access_token>

Rotating refresh

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

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

1. On a 401 from any call, call POST /auth/refresh, store the new pair, and retry the request.
2. Run one refresh at a time: requests that get a 401 at the same moment wait for the same refresh.
3. On a 401 from /auth/refresh (auth.session_revoked, auth.refresh_token_reused, auth.refresh_token_invalid) or on a 403 auth.tenant_unavailable, clear the tokens and send the user to the login screen.
4. On network errors or 5xx, do not drop the session: try again later.

Logout

• POST /auth/logout with {"refresh_token": "..."} in the body closes this session: from then on that refresh token answers 401 auth.session_revoked. It’s idempotent and doesn’t need the access token. The access token stays valid until it expires: drop it in the client.
• POST /auth/logout?all=true closes all the account’s sessions, on every device (“sign out everywhere”). It needs a valid credential: the Authorization: Bearer <access_token> header, or the refresh token in the body if the access token has already expired. Without one: 401 auth.not_authenticated.

# sign out everywhere
curl -X POST "$BASE/api/v1/auth/logout?all=true" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "Authorization: Bearer $TOKEN"

Two-factor authentication (2FA)

1. Activation: POST /auth/2fa/setup with {"current_password": "..."} returns secret and qr_uri to show as a QR code. Then POST /auth/2fa/verify with {"code": "123456", "current_password": "..."} enables 2FA, closes the other sessions, and answers with new tokens plus 10 recovery codes (recovery_codes).
2. Recovery codes: they look like xxxxx-xxxxx, are valid once, and must be shown to the user only once, in the activation response. Each one replaces the app code at login and to disable 2FA.
3. Login: with 2FA enabled, the first POST /auth/login answers 401 auth.totp_required. Repeat the same call with totp_code, which accepts the app code or a recovery code. Each TOTP code is valid once: the same code presented again gives 401 auth.totp_invalid.
4. Regeneration: POST /auth/2fa/recovery-codes with {"current_password": "..."} returns 10 new codes; the old ones stop working. GET /auth/me exposes recovery_codes_remaining (null while 2FA is off): when it gets close to 0, prompt the user to regenerate them.
5. Deactivation: POST /auth/2fa/disable with {"code": "..."} (app code or recovery code). It closes the other sessions, clears the recovery codes, and returns new tokens.

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

Deleted store

• POST /auth/login (with the right password) and POST /auth/refresh answer 403 auth.tenant_unavailable;
• any other authenticated call with a token of that store answers 401 auth.tenant_unavailable.

3. Staff token: Admin API

Authorization: Bearer <staff_access_token>

• Login is the same POST /auth/login, with a staff user’s credentials. The same rotation rules apply, with the strict reuse rule described above.
• The token carries the tenant_id claim: every session is bound to its store (leak-proof multi-tenant isolation).
• For automations and long-running agents there is the API token: it’s used as a Bearer, with no login or refresh, and has a mandatory expiry. See Manage your store via API.
• Admin mutations are audit-logged.
• Publishable keys never grant access here.

Common auth error codes