Zum Hauptinhalt springen

OAuth 2.0 (Client Credentials)

Die Energy Management API verwendet den OAuth 2.0 client_credentials-Flow. Jede Anfrage (außer GET /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 mit 403 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 mit 401 abgelehnt; 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

Tokens laufen nach 3600 Sekunden (1 Stunde) ab. Fordere ein neues Token an, bevor das aktuelle abläuft. Du kannst die Zugangsdaten auch über Authorization: Basic base64(client_id:client_secret) mit grant_type=client_credentials im Body senden (RFC 6749).

3. Token verwenden

Übergib das Token als Authorization: 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

  1. Öffne Zugriffstoken anfordern und klicke auf Try it.
  2. Gib client_id und client_secret ein, lass grant_type auf client_credentials und sende die Anfrage.
  3. Kopiere das access_token aus der Antwort.
  4. Öffne eine beliebige Endpunkt-Seite in der API-Referenz, füge das Token in das Authorization-Feld ein und sende die Anfrage.
Anfragen aus der Dokumentation gehen an die Live-Produktions-API und erreichen nur die Standorte deiner Organisation. Ein 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.