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:

Accedi al tuo account Mirox
Apri il menu Profilo (in alto a destra) e scegli Profilo
Seleziona la scheda "Token API"
Clicca su "Crea nuovo token"
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)
Clicca su "Genera token"

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

Salva subito il tuo token

Copia e conserva in modo sicuro il token - verrà visualizzato una sola volta. Se perdi il token, devi ruotarlo o crearne uno nuovo.

I token vengono creati da una sessione del browser

La creazione e la rotazione dei token richiedono una sessione web attiva e autenticata. Un token non può essere utilizzato per generare o ruotare altri token, quindi un token API da solo non può gestire il tuo insieme di token.

Token, 2FA e regole di accesso

Un token API è fatto per l'automazione. Non gli viene mai chiesto un secondo fattore, e la durata dell'accesso impostata dalla tua organizzazione non lo fa terminare. Funziona fino alla propria data di scadenza, o finché non lo revochi o lo ruoti. Una regola vale quando crei un token: finché la tua organizzazione richiede la 2FA e il tuo account non ha un secondo fattore, non puoi creare un nuovo token. Attiva prima la 2FA, con un'app di autenticazione o una passkey. I token già esistenti continuano a funzionare. Vedi Criterio di sicurezza dell'organizzazione.

Buone pratiche di sicurezza dei token

Quando lavori con i token API:

Conserva in modo sicuro - Tratta i token come password; non inserirli mai in modo fisso nel codice delle applicazioni
Usa variabili d'ambiente - Conserva i token in variabili d'ambiente o in archivi sicuri di credenziali
Limita l'ambito - Crea token con i permessi minimi necessari per l'integrazione
Imposta scadenze appropriate - Usa periodi di scadenza più brevi per le integrazioni temporanee
Pianifica la rotazione - Imposta promemoria nel calendario prima della scadenza del token per garantire la continuità del servizio
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
Revoca quelli inutilizzati - Revoca immediatamente i token che non sono più necessari
Monitora l'utilizzo - Verifica regolarmente l'attività dei token tramite l'interfaccia di Mirox

Avviso

I token scadono alla data configurata e tutte le integrazioni che li utilizzano smetteranno di funzionare immediatamente.

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.
Metric Export — limita il token alla lettura dell'esportazione dati: metriche come serie temporali, modelli di esportazione, il catalogo delle metriche, informazioni sull'impianto ed eventi. Non può modificare nulla. È il gruppo per Excel, strumenti BI e script di esportazione.
Timeseries Database — limita il token agli endpoint di interrogazione delle serie temporali, per leggere le serie di misura grezze.

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

Il gruppo si chiamava Reporting

I token che hai creato nel gruppo Reporting sono ora token Metric Export. Continuano a funzionare e leggono gli stessi link di prima, e in più ogni link del Metric Export e dell'esportazione legacy raw e dei componenti. I report che Mirox genera da sé non sono guidati da token API.

Nella pagina Esportazione dati, Prova accanto a un link di esportazione crea un token Metric Export in un solo passaggio — vedi Metric Export.

Gestione del ciclo di vita dei token

Monitoraggio dell'utilizzo dei token

Traccia l'attività dei token API tramite:

La sezione "Token API" nel tuo profilo
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:

Vai alla sezione "Token API" nel tuo profilo
Trova il token nell'elenco e scegli "Ruota"
Copia subito il nuovo segreto — viene mostrato una sola volta
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.

Pianifica la rotazione nelle finestre di manutenzione

Poiché il segreto precedente viene invalidato nel momento in cui ruoti, qualsiasi integrazione che utilizza ancora il vecchio valore inizierà a fallire. Ruota durante una finestra di manutenzione, oppure preparati ad aggiornare immediatamente il sistema che lo utilizza.

Revoca dei token

Per revocare un token:

Vai alla sezione "Token API" nel tuo profilo
Trova il token nell'elenco
Clicca su "Revoca"
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:

Problema	Possibile causa	Soluzione
401 Unauthorized	Token non valido, revocato, ruotato o scaduto	Verifica la validità del token, oppure ruotalo / creane uno nuovo
403 Forbidden	Il gruppo di permessi del token non copre l'endpoint richiesto	Usa un token in un gruppo di permessi che concede l'accesso, oppure uno con Full Access
429 Too Many Requests	Limite di frequenza superato	Rallenta e implementa una strategia di backoff esponenziale
Non è possibile creare un nuovo token	La tua organizzazione richiede la 2FA e il tuo account non ha un secondo fattore	Attiva la 2FA nel tuo profilo (app di autenticazione o passkey), poi crea il token. I token esistenti non sono interessati

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 e legge un modello di esportazione
Metric Export per Excel — link di esportazione pronti, ed Excel Power Query con il token nell'header Authorization

Suggerimento

Gli endpoint e i parametri esatti possono cambiare nel tempo. Il riferimento ufficiale e aggiornato è sempre la documentazione OpenAPI all'indirizzo /docs.

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
Metric Export — esporta le metriche come serie temporali con un token Metric Export
Metric Export API — i parametri dei link di esportazione