Token API

Un token dà a uno strumento esterno l'accesso ai dati del vostro cliente, e solo di quello. L'accesso è in lettura, più qualche scrittura mirata se la concedete. Con un token non si può mai aprire una sessione nella console.

#Creare un token

1. Aprite API pubblica (#/api-tokens, nel gruppo Connettori del menu). La schermata è riservata agli amministratori del cliente.
2. Date un Nome che dica chi lo usa («Strumento ticket», «Supervisione generale»…). È il nome che compare nel registro delle chiamate.
3. Spuntate gli Ambiti di cui lo strumento ha bisogno, non di più (vedi Ambiti dei token). read:machines e read:netdiag sono già spuntati.
4. Scegliete la Scadenza: 90 giorni, 365 giorni (predefinita), 730 giorni o mai.
5. Fate clic su Crea token. Il token compare una sola volta: copiatelo subito nello strumento che lo userà.

Un cliente può avere al massimo 20 token attivi.

Un token inizia con fsi_live_. In seguito la console ne mostra solo i primi caratteri, quanto basta per riconoscerlo.

#Usarlo

Il token va nell'intestazione Authorization di ogni chiamata:

Authorization: Bearer fsi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Per gli strumenti che non sanno compilare Authorization è accettata anche l'intestazione X-Api-Token: <token>.

Un token assente, sconosciuto, scaduto o revocato riceve 401, e lo stesso vale se il vostro cliente è disattivato. Un token valido a cui manca l'ambito della rotta riceve 403.

#Seguirne l'uso

Per ogni token la schermata API pubblica mostra il prefisso, gli ambiti, la scadenza, l'Ultima chiamata e il numero di Chiamate. Il Registro delle chiamate (ultime 100) riporta data, metodo, rotta, codice di risposta, numero di righe, durata e indirizzo di provenienza. Per le scritture viene conservato anche il corpo inviato.

#Revocare

Fate clic su Revoca accanto al token. L'effetto è quasi immediato: al massimo un minuto, il tempo che si svuoti la cache del server. Revocate senza aspettare un token che potrebbe essere stato esposto (copiato in un messaggio, finito in un repository di codice, visibile in uno screenshot), il cui strumento non serve più o il cui proprietario ha lasciato il team.

#Qualche regola di buon senso

Un token per strumento. Con un token condiviso il registro non dice più chi ha letto che cosa, e una revoca interrompe tutte le integrazioni insieme. Mettete una scadenza ai token di prova e a quelli dei fornitori esterni. Concedete il minimo indispensabile di ambiti; gli ambiti write:* sono per le integrazioni che devono davvero agire. Infine, conservate il token nel gestore di segreti dello strumento (variabile d'ambiente, vault), non in chiaro dentro uno script.

Fonte: · Docs FirstSI · aggiornato il 10/10/2026