Vai al contenuto principale

OAuth 2.0 (client credentials)

L’API Energy Management utilizza il flusso OAuth 2.0 client_credentials. Ogni richiesta (eccetto GET /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 con 403 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-key sono rifiutate con 401; 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

I token scadono dopo 3600 secondi (1 ora). Richiedi un nuovo token prima che quello attuale scada. Puoi anche inviare le credenziali tramite Authorization: Basic base64(client_id:client_secret) con grant_type=client_credentials nel body (RFC 6749).

3. Utilizzare il token

Passa il token come Authorization: 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

  1. Apri Ottenere un token di accesso e fai clic su Try it.
  2. Inserisci client_id e client_secret, lascia grant_type su client_credentials e invia la richiesta.
  3. Copia l’access_token dalla risposta.
  4. Apri una qualsiasi pagina di endpoint del Riferimento API, incolla il token nel campo Authorization e invia la richiesta.
Le richieste dalla documentazione vanno all’API di produzione e raggiungono solo le sedi della tua organizzazione. Un 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.