Authentifizierung und erster Aufruf

Für einen API-Aufruf brauchen Sie einen Access Token, den Sie mit Ihrer client_id und Ihrem client_secret anfordern. Der Token ist eine Stunde gültig: Fordern Sie ihn einmal an und verwenden Sie ihn für alle Aufrufe wieder.

Token anfordern

curl -X POST https://k8s.prod.cloud.energyincloud.com/webapp/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

Die Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:plants read:telemetry read:energy read:alarms read:controls"
}

Alternativ zu den Formularfeldern wird HTTP Basic Authentication (-u "$CLIENT_ID:$CLIENT_SECRET") akzeptiert.
Mit dem optionalen Parameter scope fordern Sie eine Teilmenge Ihrer Scopes an.
Fehler dieses Endpoints folgen dem OAuth-2.0-Format, zum Beispiel {"error": "invalid_client"}.

Gültigkeit des Tokens

Der Access Token ist 1 Stunde gültig (expires_in, in Sekunden). Es gibt keinen Refresh Token: Fordern Sie kurz vor Ablauf mit denselben Zugangsdaten einen neuen Token an und verwenden Sie den Token bis dahin für alle Aufrufe wieder. Fordern Sie nicht für jeden Aufruf einen neuen an.

Der erste Aufruf

Übergeben Sie den Token im Header Authorization und listen Sie die Anlagen auf, die Ihr Client sieht:

curl "https://api.cloud.energyincloud.com/v1/plants?limit=2" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    { "plant_id": "7b0728a9-853c-4b31-8446-a4eb00607566", "name": "Plant A",
      "country": "Italy", "timezone": "Europe/Rome", "created_at": "2025-07-03T09:12:44Z" },
    { "plant_id": "f15d7665-49c5-416b-828d-e4244d222b6f", "name": "Plant B",
      "country": "Italy", "timezone": "Europe/Rome", "created_at": "2025-09-18T14:05:10Z" }
  ],
  "pagination": { "next_cursor": "eyJpZCI6ImYxNWQ3NjY1In0=", "has_more": true }
}

Was die Response enthält:

Feld	Bedeutung
`plant_id`	stabile Kennung (UUID) der Anlage, für alle weiteren Aufrufe
`country`	registrierter Ländername, auf Englisch; leer, wenn nicht gesetzt
`timezone`	IANA-Zeitzone der Anlage: Die Energiefenster werden in dieser Zeitzone berechnet
`pagination`	ist `has_more` gleich `true`, wiederholen Sie den Aufruf mit `next_cursor` als Parameter `cursor`

limit reicht von 1 bis 200, Standard 50. Die Anlagendetails, GET /v1/plants/{plant_id}, enthalten zusätzlich location, eine Adresse als Freitext: Zeigen Sie sie an, werten Sie sie nicht aus.

Wenn der Aufruf fehlschlägt

401: Der Token fehlt, ist abgelaufen oder ungültig. Fordern Sie einen neuen Token an.
403: Dem Client fehlt der erforderliche Scope. Kontaktieren Sie zeroCO2.
Alle weiteren Codes finden Sie in der Tabelle unter „Limits, Fehler und Support“.