Autenticazione e prima chiamata

Per chiamare l'API serve un access token, che ottieni con il tuo client_id e il tuo client_secret. Il token vale un'ora: lo chiedi una volta e lo riusi per tutte le chiamate.

Ottenere un token

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"

La risposta:

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

In alternativa ai campi del form è accettata l'autenticazione HTTP Basic (-u "$CLIENT_ID:$CLIENT_SECRET").
Il parametro facoltativo scope richiede un sottoinsieme dei tuoi scope.
Gli errori di questo endpoint seguono il formato OAuth 2.0, per esempio {"error": "invalid_client"}.

Durata del token

L'access token è valido 1 ora (expires_in, in secondi). Non esiste un refresh token: chiedi un nuovo token con le stesse credenziali poco prima della scadenza e, fino ad allora, riusa lo stesso token per tutte le chiamate. Non chiederne uno a ogni chiamata.

La prima chiamata

Passa il token nell'header Authorization ed elenca gli impianti che il tuo client vede:

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 }
}

Cosa trovi nella risposta:

Campo	Significato
`plant_id`	identificativo stabile (UUID) dell'impianto, da usare in tutte le altre chiamate
`country`	nome del paese come registrato, in inglese; vuoto se non impostato
`timezone`	fuso orario IANA dell'impianto: le finestre di energia sono calcolate in questo fuso
`pagination`	se `has_more` è `true`, ripeti la chiamata passando `next_cursor` come parametro `cursor`

limit va da 1 a 200, con valore predefinito 50. Il dettaglio di un impianto, GET /v1/plants/{plant_id}, aggiunge location, un indirizzo in testo libero: mostralo, non interpretarlo.

Se la chiamata non riesce

401: il token manca, è scaduto o non è valido. Chiedi un nuovo token.
403: il client non ha lo scope richiesto. Contatta zeroCO2.
Tutti gli altri codici sono nella tabella di "Limiti, errori e supporto".