MenuFacile2.0

AutenticazioneDEV

Gestione token API: generazione, uso, rotazione, revoca.

L'API V1 di MenuFacile usa Laravel Sanctum personal access token. Ogni token è legato a un utente del pannello admin (tipicamente l'account proprietario del ristorante) ed è circoscritto a un singolo tenant: il token di ducatarocco.menufacile.it non funziona su altroristorante.menufacile.it.

Quando serve il token

Categoria endpoint Esempi Token Scope richiesto
Pubblici (read-only) GET /api/v1/menu, categories, items, restaurant, theme, allergens Non necessario –
Admin scrittura POST/PUT/DELETE /api/v1/admin/{categories,items,types,wineries}, PUT /admin/settings, PUT /admin/theme Obbligatorio menu:write
Admin analytics GET /api/v1/admin/analytics/{overview,items,sections,allergens,insights} Obbligatorio analytics:read

💡 Per integrare il menu su un sito istituzionale ti basta consumare gli endpoint pubblici senza token. Il token serve solo per gli endpoint admin.

Generare un token

Vai sul pannello admin del ristorante: https://<tenant>.menufacile.it/admin/api-tokens.

  1. Click Genera nuovo token
  2. Compila il nome descrittivo (es. "Sito agenzia X", "App iOS")
  3. Spunta gli scope richiesti (vedi sezione Scope qui sotto)
  4. Click Genera: appare un banner con il token in chiaro
  5. Copialo subito. Per sicurezza non sarà più visibile dopo aver chiuso il banner

Il token ha forma <id>|<plain>, esempio: 12|aBcDeF1234ZyXwVu....

Scope (abilities)

Ogni token ha uno o più scope, scelti al momento della generazione e immutabili.

Scope Cosa abilita
menu:read Lettura menu — assegnalo a token usati per leggere dati (è buona pratica anche se gli endpoint pubblici non lo verificano)
menu:write Scrittura su sezioni, piatti, sottocategorie, cantine, settings, theme
analytics:read Lettura degli endpoint GET /api/v1/admin/analytics/*

Un token può combinare più scope (es. menu:write + analytics:read per un'integrazione che deve sia scrivere il menu sia leggere le statistiche).

Errore 403 — scope insufficiente

Se chiami un endpoint admin con un token privo dello scope richiesto:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{ "message": "Invalid ability provided." }

Fix: revoca il token e generane uno nuovo selezionando anche lo scope mancante. Gli scope sono fissati alla generazione, non si possono modificare a posteriori.

Usare il token

Inviare il token nell'header Authorization con prefisso Bearer:

curl -H "Authorization: Bearer 12|aBcDeF1234ZyXwVu..." \
     -H "Accept: application/json" \
     https://ducatarocco.menufacile.it/api/v1/admin/items

In JavaScript (server-side, MAI nel browser):

const res = await fetch('https://ducatarocco.menufacile.it/api/v1/admin/items', {
  headers: {
    'Authorization': `Bearer ${process.env.MENUFACILE_TOKEN}`,
    'Accept': 'application/json',
  },
});

⚠️ Il token va trattato come una password: mai committarlo nel repository, mai esporlo nel JavaScript del browser. Sul frontend usa una proxy server-side (es. wp_remote_get su WordPress, una API route Next.js, una funzione Vercel/Netlify).

Token mancante o invalido

Chiamata a un endpoint admin senza header Authorization o con token revocato/inesistente:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Unauthenticated."
}

Soluzione: verifica che il token sia presente, non scaduto/revocato, e copiato per intero (incluso il prefisso <id>|).

Rotazione e revoca

Rotazione consigliata ogni 90 giorni o quando un dipendente di uno studio/agenzia cambia ruolo:

  1. Pannello → Token API → click sul token vecchio
  2. Click Revoca (cestino) → conferma
  3. Genera nuovo token con stesso nome
  4. Aggiorna la configurazione del consumer (sito, app, integrazione)

Revoca immediata in caso di compromissione: stessa procedura. La revoca è effettiva entro pochi secondi (no cache lato server).

Ciclo di vita

Token vs IP allowlist

MenuFacile non offre IP allowlist nativa: la sicurezza poggia sul token. Se hai bisogno di restringere a IP fissi (raro per integrazioni di menu pubblici), gestisci il filtro a livello CDN/firewall davanti al tuo proxy.

Rate limit

I token non aumentano i limiti per gli endpoint pubblici (sono limitati per tenant + IP). Per i dettagli dei rate limit per categoria, vedi Limiti d'uso.

Hai bisogno di aiuto?

Scrivi a info@menufacile.it.