Token API
I token API ti permettono di collegare sistemi esterni, script e strumenti alla piattaforma Mirox con credenziali con ambito limitato e revocabili, che non espongono mai la tua password. Ogni token autentica le richieste machine-to-machine per tuo conto, così puoi automatizzare la reportistica ed esportare le metriche senza condividere il tuo login.
Concetto di token
Ogni token appartiene all'utente che lo ha creato e si comporta come quell'utente, entro certi limiti:
- Collegato al tuo account — un token agisce per tuo conto, e tutto ciò che fa viene attribuito a te nel registro di audit.
- Tetto di permessi — un token non può mai raggiungere nulla che tu stesso non possa raggiungere. Il tuo ruolo e il tuo accesso alle risorse limitano sempre ciò che il token può vedere.
- Limitato dal gruppo di permessi — al momento della creazione scegli un gruppo di permessi per restringere ulteriormente il token (vedi sotto).
- Mostrato una sola volta — il valore completo del token viene visualizzato una sola volta al momento della creazione. Conservalo in modo sicuro; Mirox ne mantiene solo una copia con hash e non potrà mai mostrarlo di nuovo.
In questo modo l'automazione resta tracciabile: anche se un token viene compromesso, è limitato a un solo ambito, facile da revocare e isolato dagli altri tuoi token.
Gruppi di permessi
Quando crei un token scegli un gruppo di permessi che definisce ciò che può fare:
| Gruppo | Cosa può fare il token |
|---|---|
| Full Access | Agisce con il tuo accesso completo: ogni superficie API che puoi raggiungere. |
| Reporting | Genera e scarica solo report ed esportazioni. |
| Timeseries Database | Legge solo le metriche delle serie temporali. |
Un gruppo non amplia mai il tuo accesso; restringe soltanto il token rispetto ai tuoi permessi. Per la definizione completa di ciascun gruppo, consulta la sezione gruppi di permessi API della documentazione sul sistema di permessi.
Adatta il gruppo al compito
Assegna a ogni integrazione il gruppo più ristretto che funziona ancora. Un'attività di report notturno necessita solo di Reporting; un client di sola lettura delle metriche necessita solo di Timeseries Database. In questo modo si limita il raggio d'azione in caso di fuga di un token.
Creazione e gestione dei token
Gestisci i tuoi token dal tuo profilo. La piattaforma copre l'intero ciclo di vita:
Creazione di un token
- Nome e descrizione — un'etichetta chiara e una nota per ricordare a cosa serve ciascun token.
- Gruppo di permessi — scegli uno dei gruppi sopra elencati.
- Scadenza — facoltativa. I token hanno per impostazione predefinita una durata di un anno, e puoi impostare qualsiasi scadenza fino a un massimo di cinque anni.
- Rivelazione una tantum — il token completo viene mostrato una sola volta alla creazione, poi mai più.
Puoi mantenere fino a 64 token attivi per account.
Creazione e rotazione richiedono una sessione con login attivo
La creazione, la rotazione o l'eliminazione di un token richiede un login attivo dal browser (sessione con cookie). Non puoi usare un token API per generarne o ruotarne un altro: questo impedisce a un token trafugato di crearne altri in modo silenzioso.
Rotazione di un token
La rotazione sostituisce il segreto di un token sul posto, senza modificarne il nome, la descrizione o il gruppo di permessi:
- Viene emesso un nuovo segreto e mostrato una sola volta.
- Il vecchio segreto smette di funzionare immediatamente.
- La scadenza viene reimpostata e la cronologia di utilizzo viene cancellata.
La rotazione è il modo consigliato per rinnovare le integrazioni di lunga durata secondo una pianificazione, o per rispondere a una sospetta fuga, senza dover riconfigurare quale integrazione usa quale token.
Monitoraggio e revoca
- Inventario — elenca tutti i tuoi token con nome, gruppo di permessi, date di creazione e di scadenza.
- Informazioni sull'utilizzo — visualizza quando ciascun token è stato usato l'ultima volta, insieme all'IP, alla posizione, al browser e al sistema operativo registrati in quel momento. Il valore del token non viene mai mostrato di nuovo.
- Revoca immediata — elimina un token per invalidarlo all'istante. La revoca di un token non influisce mai sugli altri.
Casi d'uso comuni
I token API supportano un'ampia gamma di scenari di integrazione.
Reportistica ed esportazione dei dati
- Pianifica la generazione e il download automatici dei report.
- Alimenta i dati sulle prestazioni in data warehouse e pipeline di analisi.
- Alimenta dashboard esterne e strumenti di reportistica direzionale.
Accesso alle metriche delle serie temporali
- Interroga le metriche storiche con MiroxQL, il formato di query supportato per l'accesso programmatico e ai dati grezzi.
- Collega strumenti di analisi in sola lettura all'API di esportazione delle metriche.
- Estrai metriche storiche per l'analisi delle tendenze e per dashboard esterne.
Sicurezza e controllo
- Isolamento dei token — un token compromesso non espone mai la tua password né gli altri tuoi token.
- Rotazione pianificata — ruota periodicamente i token di lunga durata usando l'azione di rotazione, mantenendo la stessa configurazione.
- Validità a tempo limitato — imposta una scadenza affinché i token abbandonati decadano automaticamente.
- Attribuzione completa — ogni azione che un token compie viene registrata a tuo nome, così l'utilizzo resta tracciabile e verificabile.
Funzionalità correlate
- Sistema di permessi — come funzionano i gruppi di permessi e il controllo degli accessi
- Report — generazione automatica di report che un token può guidare
- MiroxQL — interroga le metriche storiche con un token Timeseries Database
- Guida all'uso dei token API — creazione passo-passo dei token ed esempi