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, 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-tokencrea 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-tokenrisponde HTTP 401 conerror_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.
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
- Mai un
auth/get-tokenfuori 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. - Si riusa il token finché Kross non dice
error_code 2. La scadenza scritta in tabella è una stima. Quando arrivaerror_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. - 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.
error_code 12apre 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.- 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.
error_code 12 resta comunque attivo, per singola istanza.
Chi la usa oggi
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 suerror_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).
Cosa fare quando arriva
error_code 12 / pool pieno
- Non rigenerare credenziali né token dei custom tool: non c’entrano e non svuotano il pool.
- 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.
- 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.
- 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.
Se scrivi codice nuovo che parla con Kross
- Non scrivere un
fetchaauth/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.