> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Kross: regole per chiunque scriva codice che parla con KrossBooking

> Il limite di 50 token attivi per struttura, la cache unica condivisa, il freno su error_code 12, il tetto, l'allarme e cosa fare quando arriva. Vale per gateway, piattaforma, MCP locali, script e siti.

Questa pagina è per **chi scrive o modifica codice** che chiama l'API di KrossBooking: gateway dell'assistente (`mcp.mattone.co`), piattaforma, MCP locali, script, siti. Se lavori su un sito di prenotazione diretta leggi anche [Cache del token Kross sui siti di prenotazione diretta](/integrazioni/direct-booking/cache-token-kross), che copre build, controllo di salute e avviso giornaliero dei siti. Qui ci sono le regole comuni a tutti.

## Il limite

* Ogni chiamata a `auth/get-token` crea un **token nuovo**. Kross ne ammette al massimo **50 attivi per struttura** (`hotel_id`), indipendentemente da chi li ha creati: piattaforma, gateway, siti e script sulla stessa struttura pescano dallo **stesso** pool.
* Un token vale **7 giorni dall'ultimo uso**: ogni chiamata lo rinnova. Non si può revocare né chiudere.
* Oltre il tetto, `auth/get-token` risponde **HTTP 401 con `error_code 12`** («Too many active tokens»). Da quel momento la struttura è ferma per **tutti** finché un token vecchio non scade: niente disponibilità sul sito, custom tool Conduit in errore, voice agent senza dati. Non sono le credenziali.

Altri codici da non confondere: **`error_code 2`** = quel token non vale più (HTTP 401, «Invalid token or token expired»); **5 / 11 / 18** = credenziali sbagliate; **429** = troppe richieste al minuto (limite diverso, 10/min).

## Le cinque regole

1. **Mai un `auth/get-token` fuori dalla cache condivisa.** Esiste una sola cache per tutti i sistemi Mattone: una tabella nel database della piattaforma, una riga per struttura. Prima di autenticarti chiedi lì; se c'è un token, usalo. Una cache in memoria del singolo processo non conta: su Vercel ogni istanza nuova è un token nuovo.
2. **Si riusa il token finché Kross non dice `error_code 2`.** La scadenza scritta in tabella è una stima. Quando arriva `error_code 2`, togli dalla tabella **solo quel token** (se un altro sistema l'ha già sostituito, usa il suo) e riprova **una volta**. Mai un secondo giro: un ritentativo senza tetto è un token nuovo a ogni giro.
3. **Una sola autenticazione alla volta per struttura.** Prima dell'auth il codice chiede il permesso alla cache, che risponde: c'è già un token / tocca a te / un altro sta autenticando / freno attivo / tetto raggiunto. Solo «tocca a te» autorizza **una** chiamata. Chi trova «un altro sta autenticando» aspetta e rilegge, e se non arriva niente **rinuncia con un errore temporaneo**: non si autentica in parallelo.
4. **`error_code 12` apre il freno, e il token in tabella non si tocca.** Il freno è condiviso: per **15 minuti** nessun sistema chiede token nuovi per quella struttura. Il token già in tabella resta, perché con il pool pieno è l'unico che funziona ancora. Cancellarlo (lo faceva il gateway fino al 08/10/2026) ferma la struttura per giorni.
5. **Tetto: 40 token creati in 7 giorni per struttura.** Raggiunto, nessun sistema ne crea altri finché la finestra non scorre. Con un riuso corretto se ne creano uno o due a settimana: 40 vuol dire che qualcosa autentica invece di riusare.

Se la cache non risponde (database giù), i sistemi si autenticano come prima: un'interruzione del database non deve fermare gli ospiti. Il freno su `error_code 12` resta comunque attivo, per singola istanza.

## Chi la usa oggi

| Sistema | Passa dalla cache con freno e tetto |
| - | - |
| Gateway dell'assistente (`mcp.mattone.co`, custom tool Conduit degli studenti, voice agent) | sì |
| Piattaforma (letture, test di collegamento, controllo notturno delle connessioni) | sì. Il controllo notturno **riusa** il token con una lettura vera, e si autentica solo se il token manca o è stato rifiutato |
| MCP KrossBooking locale | sì |
| Mattone Operations (sincronizzazione ricavi) | non si autentica più: legge dalla piattaforma |
| Siti di prenotazione diretta | vedi [Cache del token Kross](/integrazioni/direct-booking/cache-token-kross) |

I custom tool Conduit non parlano mai con Kross direttamente: chiamano il gateway (o, per Cosmica Italia, il sito di prenotazione), che gestisce il token. Un custom tool nuovo deve fare lo stesso.

## Quale numero guardare

Kross **conta i token per account**, non solo per singola struttura, e quel conteggio **non è leggibile da noi**: nessuna API restituisce quanti token attivi ha un account. Il registro e la cache di Mattone vedono solo i token creati dai **nostri** sistemi; quelli creati fuori (il pannello Kross, un altro fornitore collegato allo stesso account, script di altri) non li vediamo. Per questo nessun numero calcolato da noi dice «il pool è al 30%».

L'**unico indicatore affidabile** è l'allarme **kross-token-watch** qui sotto: scatta su `error_code 12` reali e sui ritmi anomali di creazione. Se non arriva, non c'è un pool pieno che conosciamo; se arriva, è vero.

## L'allarme

Ogni token nuovo scritto nella cache, da qualunque sistema, viene registrato con la sua provenienza. Ogni 10 minuti la piattaforma (controllo **kross-token-watch**) controlla e scrive nel canale Slack **#mattone-coding** quando:

* una struttura ha ricevuto **`error_code 12`** (una volta per evento);
* una struttura ha raggiunto il **tetto** dei 40 token;
* una struttura ha più di **10 token nuovi in 24 ore** (al massimo un avviso ogni 6 ore per struttura).

Il messaggio dice la struttura e quali sistemi hanno creato i token.

## Cosa fare quando arriva

**`error_code 12` / pool pieno**

1. Non rigenerare credenziali né token dei custom tool: non c'entrano e non svuotano il pool.
2. Guarda nel messaggio **chi** ha creato i token nelle ultime 24 ore. Se un sistema ne ha creati molti, è lui il guasto: spesso un sito o un processo che non vede la cache (impostazioni mancanti) o un progetto dimenticato acceso.
3. Ferma quel produttore (metti in pausa il progetto, correggi le impostazioni). Il pool si svuota da solo man mano che i token inutilizzati arrivano ai 7 giorni: possono servire **giorni**, non minuti.
4. Nel frattempo i sistemi che hanno già un token in tabella continuano a funzionare. Avvisa chi gestisce gli ospiti di quella struttura se i check-in automatici sono fermi.

**Troppi token in 24 ore (senza 12)**
È il segnale in anticipo. Stessa indagine del punto 2: trova chi autentica invece di riusare e correggilo prima che il pool si riempia.

**Tetto raggiunto**
Nessun sistema crea più token per quella struttura per qualche giorno. Se i sistemi funzionano col token in tabella non serve fare altro che trovare il colpevole; se la struttura è ferma serve un intervento tecnico.

## Se scrivi codice nuovo che parla con Kross

* Non scrivere un `fetch` a `auth/get-token`. Usa il modulo del token condiviso del repository in cui lavori (gateway, piattaforma, MCP locale o template dei siti).
* Ogni chiamata dati deve distinguere `error_code 2` (sostituisci il token, una volta), `error_code 12` (freno, token intatto) e 429 (attendi, nessun ritentativo immediato).
* Un controllo periodico (health, cron) **non** deve autenticarsi a ogni giro: deve riusare il token o non toccare Kross.
* La chiave di tutto è l'`hotel_id`, mai lo studente o la riga di integrazione: due righe sulla stessa struttura condividono lo stesso pool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.