OAuth 2.0 (Client Credentials)
Die Energy Management API verwendet den OAuth 2.0 client_credentials-Flow. Jede Anfrage (außerGET /health und POST /oauth/token) erfordert ein
Bearer-Token:
1. Zugangsdaten erstellen
Jede Nutzerin und jeder Nutzer deiner Organisation kann OAuth-Client-Zugangsdaten im RiDERgy-Dashboard erstellen: Öffne Mein Konto, gehe zu OAuth Clients und wähle Neuen Client erstellen. Zuvor muss RiDERgy die Energy Management API für deine Organisation aktivieren; ohne Aktivierung schlagen Anfragen mit403 FEATURE_NOT_ENABLED fehl.
- Client-ID (
emcl_...): nicht geheim. Sie bleibt im Dashboard sichtbar. - Client Secret (
emcs_...): wird nur einmal beim Erstellen angezeigt. Speichere es sofort in einem Passwortmanager oder Secrets-Tresor. RiDERgy kann es nicht erneut anzeigen; geht es verloren, erstelle einen neuen Client und widerrufe den alten. - Wähle nur die Scopes, die deine Integration braucht. Neue Clients starten mit Leserechten.
- Ein Client gehört deiner Organisation, nicht der Person, die ihn erstellt hat. Er funktioniert also weiter, wenn diese Person das Unternehmen verlässt.
- RiDERgy vergibt keine API-Keys. Anfragen mit einem
x-api-key-Header werden mit401abgelehnt; verwende immer ein Bearer-Token wie unten beschrieben.
Noch kein Dashboard-Login? Während deine Organisation eingerichtet wird,
kann RiDERgy einen temporären Client ausstellen, der nach 7 Tagen abläuft.
Client-ID und Secret erhältst du über zwei getrennte Kanäle. Sobald du einen
Dashboard-Login hast, erstelle deinen eigenen Client und bitte RiDERgy, den
temporären zu widerrufen.
2. Zugriffstoken anfordern
Authorization: Basic base64(client_id:client_secret)
mit grant_type=client_credentials im Body senden (RFC 6749).
3. Token verwenden
Übergib das Token alsAuthorization: Bearer <token> bei jeder Anfrage:
- Dein Mandant (Tenant) ist im Token eingebettet und kann nicht manipuliert werden — Zugangsdaten eines Mandanten können nicht auf Daten eines anderen Mandanten zugreifen.
- Ein abgelaufenes oder ungültiges Token liefert
401 UNAUTHORIZED. - Ein Token ohne den erforderlichen Scope liefert
403 INSUFFICIENT_SCOPE.
Scopes
Tokens enthalten Scopes, die den Zugriff auf Endpunkte steuern:
Anfragen an Endpunkte, die einen Scope erfordern, den das Token nicht hat,
schlagen mit
403 INSUFFICIENT_SCOPE fehl.
In der Dokumentation testen
- Öffne Zugriffstoken anfordern und klicke auf Try it.
- Gib
client_idundclient_secretein, lassgrant_typeaufclient_credentialsund sende die Anfrage. - Kopiere das
access_tokenaus der Antwort. - Öffne eine beliebige Endpunkt-Seite in der API-Referenz, füge das Token in das Authorization-Feld ein und sende die Anfrage.
POST/PUT ändert echte
Ladelimits; teste daher mit einem Client mit Leserechten, wenn du nichts
ändern willst.
Zugangsdaten rotieren und widerrufen
- Rotieren: Erstelle einen neuen Client, stelle deine Integration darauf um und widerrufe dann den alten Client.
- Widerrufen: im Dashboard neben dem Client. Der Widerruf wirkt sofort: Bereits ausgestellte Tokens dieses Clients funktionieren ab der nächsten Anfrage nicht mehr.
- Abgelaufene temporäre Clients funktionieren ebenso nicht mehr.

