Token API

I token API offrono ai tuoi sistemi esterni e script un accesso sicuro e con ambito alla piattaforma Mirox senza condividere le tue credenziali di accesso. Li crei nel tuo profilo, assegni a ciascuno solo i permessi di cui ha bisogno e puoi revocarli o ruotarli in qualsiasi momento.

Panoramica

A differenza del tuo nome utente e password, un token API:

• Possiede un gruppo di permessi specifico che limita ciò a cui può accedere
• Ha una data di scadenza configurabile (predefinita di un anno, massimo cinque anni)
• Può essere ruotato verso un nuovo segreto o revocato singolarmente, senza toccare il tuo account o gli altri tuoi token
• Registra la propria cronologia di utilizzo (ora dell'ultimo utilizzo, IP di origine, posizione, browser e sistema operativo) così puoi vedere il comportamento di ciascuna integrazione

Puoi detenere fino a 64 token alla volta.

Creazione dei token API

I token API possono essere creati tramite l'interfaccia web di Mirox:

1. Accedi al tuo account Mirox
2. Apri il menu Profilo (in alto a destra) e scegli Profilo
3. Seleziona la scheda "Token API"
4. Clicca su "Crea nuovo token"
5. Configura le impostazioni del token:
   • Nome (etichetta descrittiva per il token)
   • Data di scadenza (predefinita a 1 anno se non specificata, massimo 5 anni)
   • Ambito dei permessi (risorse e azioni specifiche a cui il token può accedere)
6. Clicca su "Genera token"

Apri in Mirox: Profilo ▸ Token API — gestisci i tuoi token dal menu Profilo ▸ Profilo, quindi dalla scheda "Token API".

Buone pratiche di sicurezza dei token

Quando lavori con i token API:

1. Conserva in modo sicuro - Tratta i token come password; non inserirli mai in modo fisso nel codice delle applicazioni
2. Usa variabili d'ambiente - Conserva i token in variabili d'ambiente o in archivi sicuri di credenziali
3. Limita l'ambito - Crea token con i permessi minimi necessari per l'integrazione
4. Imposta scadenze appropriate - Usa periodi di scadenza più brevi per le integrazioni temporanee
5. Pianifica la rotazione - Imposta promemoria nel calendario prima della scadenza del token per garantire la continuità del servizio
6. Ruota regolarmente - Usa l'azione integrata Ruota per rinnovare periodicamente il segreto di un token prima della sua scadenza, soprattutto per i sistemi di produzione
7. Revoca quelli inutilizzati - Revoca immediatamente i token che non sono più necessari
8. Monitora l'utilizzo - Verifica regolarmente l'attività dei token tramite l'interfaccia di Mirox

Utilizzo dei token API

I token API vengono utilizzati nelle richieste HTTP come Bearer token nell'header Authorization:

Authorization: Bearer your-api-token

Gli esempi seguenti richiedono un token nel gruppo di permessi Full Access.

Esempio di richiesta HTTP

GET /api/v1/park HTTP/1.1
Host: service.mirox.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Esempio con Curl

curl -X GET \
  https://service.mirox.io/api/v1/park \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Permessi dei token

I token API sono soggetti al Livello di permessi dei token API della piattaforma Mirox. Punti chiave sui permessi dei token:

• I token ereditano i permessi dall'utente che li ha creati (mai di più)
• I permessi possono essere ulteriormente limitati su base funzionale
• I token operano all'interno dello stesso modello di permessi gerarchico degli account utente
• Tutti i controlli di sicurezza della piattaforma si applicano all'accesso basato su token

Per informazioni dettagliate su come i token API si inseriscono nell'architettura complessiva dei permessi, consulta la documentazione del Sistema di permessi.

Gruppi di permessi

Quando crei un token, scegli uno dei tre gruppi di permessi che ne delimitano l'ambito d'azione:

• Full Access — concede al token gli stessi permessi del tuo account utente, all'interno del tuo ambito. Qualsiasi servizio che lo utilizza può agire per tuo conto su tutta la piattaforma, quindi scegli questa opzione solo quando un'integrazione necessita realmente di un accesso ampio.
• Reporting — limita il token alle funzionalità di reporting: generazione di report ed esportazione di dati.
• Timeseries Database — limita il token agli endpoint di interrogazione delle serie temporali, per estrarre dati di misurazione in modo programmatico (ad esempio con MiroxQL).

Scegli il gruppo più ristretto che copre la tua integrazione. Un token Reporting o Timeseries Database non può raggiungere nulla al di fuori del suo ambito, il che limita il raggio d'impatto in caso di fuga.

Gestione del ciclo di vita dei token

Monitoraggio dell'utilizzo dei token

Traccia l'attività dei token API tramite:

1. La sezione "Token API" nel tuo profilo
2. I log di audit che mostrano quando e come è stato utilizzato ciascun token

Rotazione dei token

La rotazione sostituisce il segreto di un token senza modificarne il nome, il gruppo di permessi o la posizione nel tuo elenco di token. Questo ti consente di rinnovare una chiave secondo una pianificazione, o di reagire a una sospetta fuga, mantenendo la stessa voce di token nella configurazione delle tue integrazioni.

Per ruotare un token:

1. Vai alla sezione "Token API" nel tuo profilo
2. Trova il token nell'elenco e scegli "Ruota"
3. Copia subito il nuovo segreto — viene mostrato una sola volta
4. Aggiorna il segreto nell'integrazione che lo utilizza

La rotazione emette un nuovo segreto, reimposta la finestra di scadenza e cancella la cronologia di utilizzo registrata del token. Il vecchio segreto smette di funzionare immediatamente, quindi aggiorna le tue integrazioni come parte della rotazione.

Revoca dei token

Per revocare un token:

1. Vai alla sezione "Token API" nel tuo profilo
2. Trova il token nell'elenco
3. Clicca su "Revoca"
4. Conferma l'azione

La revoca ha effetto immediato e qualsiasi richiesta successiva che utilizza il token fallirà.

Limitazioni d'uso

I token API sono soggetti agli stessi limiti di frequenza degli account utente normali. Per i dettagli su queste limitazioni, consulta la sezione Limitazione della frequenza nella documentazione dei Concetti di autenticazione.

Risoluzione dei problemi

Problemi comuni dei token e relative soluzioni:

Esempi di codice

Per codice funzionante che utilizza un token API end-to-end, consulta:

• Generatore di report esterno — uno script Python che si autentica con un token ed estrae un'esportazione di metriche
• MiroxQL — il linguaggio di interrogazione per estrarre dati di serie temporali con un token Timeseries Database

Funzionalità correlate

• Panoramica API — il punto di accesso alla Mirox REST API e alla sua documentazione aggiornata
• Sistema di permessi — come i gruppi di permessi dei token si inseriscono nel modello dei ruoli della piattaforma
• Autenticazione — sessioni, accesso a due fattori e i limiti di frequenza che si applicano anche ai token
• MiroxQL — interroga i dati di serie temporali in modo programmatico con un token Timeseries Database
• API di esportazione metriche — esporta dati di misurazione e report con un token Reporting