OAuth 2.0 (client credentials)
L’API Energy Management utilizza il flusso OAuth 2.0 client_credentials. Ogni richiesta (eccettoGET /health e POST /oauth/token) richiede un
token Bearer:
1. Creare le credenziali
Qualsiasi utente della tua organizzazione può creare credenziali client OAuth nella dashboard di RiDERgy: apri Il mio account, vai a OAuth Clients e scegli Crea nuovo client. Prima RiDERgy deve attivare l’API Energy Management per la tua organizzazione; senza attivazione le richieste falliscono con403 FEATURE_NOT_ENABLED.
- Client ID (
emcl_...): non segreto. Resta visibile nella dashboard. - Client secret (
emcs_...): mostrato una sola volta, alla creazione. Salvalo subito in un password manager o archivio dei segreti. RiDERgy non può mostrarlo di nuovo; se lo perdi, crea un nuovo client e revoca il vecchio. - Scegli solo gli scope di cui la tua integrazione ha bisogno. I nuovi client partono in sola lettura.
- Un client appartiene alla tua organizzazione, non alla persona che l’ha creato, quindi continua a funzionare se quella persona se ne va.
- RiDERgy non rilascia chiavi API. Le richieste con un header
x-api-keysono rifiutate con401; usa sempre un token Bearer come descritto sotto.
Non hai ancora un accesso alla dashboard? Durante l’onboarding della tua
organizzazione RiDERgy può rilasciare un client temporaneo che scade dopo
7 giorni. Riceverai client ID e secret tramite due canali separati. Quando avrai
un accesso, crea il tuo client e chiedi a RiDERgy di revocare quello temporaneo.
2. Ottenere un token di accesso
Authorization: Basic base64(client_id:client_secret)
con grant_type=client_credentials nel body (RFC 6749).
3. Utilizzare il token
Passa il token comeAuthorization: Bearer <token> in ogni richiesta:
- Il tuo tenant è incorporato nel token e non può essere contraffatto — le credenziali di un tenant non possono accedere ai dati di un altro.
- Un token scaduto o non valido restituisce
401 UNAUTHORIZED. - Un token senza lo scope richiesto restituisce
403 INSUFFICIENT_SCOPE.
Scopes
I token contengono scopes che controllano quali endpoint sono accessibili:
Le richieste a endpoint che richiedono uno scope che il token non possiede
falliranno con
403 INSUFFICIENT_SCOPE.
Provare nella documentazione
- Apri Ottenere un token di accesso e fai clic su Try it.
- Inserisci
client_ideclient_secret, lasciagrant_typesuclient_credentialse invia la richiesta. - Copia l’
access_tokendalla risposta. - Apri una qualsiasi pagina di endpoint del Riferimento API, incolla il token nel campo Authorization e invia la richiesta.
POST/PUT cambia
limiti di ricarica reali, quindi prova con un client in sola lettura se non
vuoi applicare modifiche.
Ruotare e revocare le credenziali
- Ruotare: crea un nuovo client, passa la tua integrazione al nuovo client, poi revoca il vecchio.
- Revocare: nella dashboard, accanto al client. La revoca è immediata: i token già emessi per quel client smettono di funzionare alla richiesta successiva.
- I client temporanei scaduti smettono di funzionare allo stesso modo.

