# Token API

# 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](demo-environment.md)).

## 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`:

```bash
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](/docs/developer/mcp-server).
## 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.


---
> Source: https://placeful-app.com/docs/developer/api-tokens