Token API

I token API (Laravel Sanctum) autenticano le richieste senza cookie di sessione. Features::api() di Jetstream è attivo, quindi ogni utente autenticato può gestire i token su Profilo → Token API (/user/api-tokens).

Le persone demo non possono creare token API e i token di una persona sono rifiutati in autenticazione — le persone sono solo per impersonificazione (vedi ambiente demo).

Creare un token

1. Inserisci un nome e seleziona le abilities che il token deve avere.
2. Il token in chiaro viene mostrato una volta sola — copialo subito.

Abilities

Le abilities offerte sono create, read, update, delete, companies.sync, areas.sync, events.sync, widget.manage, tables.sync, venue_items.sync (default: read).

L'ability è necessaria ma non sufficiente: HasCompanies::hasCompanyPermission richiede inoltre che l'utente del token possegga il permesso azienda corrispondente. Es. companies.sync funziona solo quando il token ha l'ability e l'utente ha il permesso companies.sync su quell'azienda (owner/admin di default).

Usare un token

Authorization: Bearer <token>

Testalo su GET /api/user:

curl -H "Authorization: Bearer <token>" https://tuo-dominio/api/user

Sync API

I token guidano la sync API in ingresso — PUT /api/v1/companies/{company} e gli endpoint area sotto /api/v1/companies/{company}/areas — gated dal middleware ability: e dalle policy sync, rate-limited a 60 req/min keyed sul token. Riferimento endpoint completo: docs/api-integration.md nel repo.

Server MCP (POST /mcp/bookings)

Ogni chiamata tool attraverso il server MCP richiede l'ability mappata a quel tool, verificata prima di qualsiasi query — un token di sola read riceve {"error": "forbidden"} sui tool di scrittura. La route è rate-limited a 60 richieste/min per token (bucket condiviso con la sync API). Il controllo permesso aziendale si applica comunque.

Ability	Tool
read	list-events, get-event, list-event-types, get-availability, next-available-event, find-slot, list-bookings, get-booking, search-bookings, list-pending-approvals, list-areas, list-tables, list-venue-items, list-orders, get-order, get-kpi, list-menu-items, list-waitlist-entries, get-guest, list-inquiries, get-stock-levels
create	create-booking
update	update-booking, mark-booking-service, check-in-booking, assign-table-to-booking, offer-waitlist-spot, publish-event, convert-inquiry, toggle-menu-item-sold-out
delete	cancel-booking

create-booking accetta bookable_type event, time, seat, seat_time, area — solo foglie prenotabili: un padre che possiede ancora figli risponde {"error": "pick_a_leaf", "children": [...]} con gli id delle foglie su cui riprovare.

Oltre ai tool il server espone risorse in sola lettura (docs://catalog per l'indice dei documenti, docs://{category}/{slug} per una pagina, changelog://index per i rilasci) e prompt — flussi già pronti come daily-service-brief e fill-cancelled-slot che istruiscono il client su quali tool chiamare. Entrambi richiedono l'ability read. Riferimento completo: Server MCP.

Scadenza

I nuovi token scadono dopo 90 giorni (SANCTUM_TOKEN_TTL_DAYS; imposta 0 per disattivare). La data di scadenza compare accanto a ogni token nella lista del profilo — rigenera il token prima di quella data. I token creati prima di questa modifica non hanno scadenza (Nessuna scadenza) e continuano a funzionare finché non vengono revocati.

Revoca

Revoca un token dalla pagina profilo. La revoca è immediata; le richieste in volo con il token revocato falliscono alla chiamata successiva.