Authentication

The API is protected by OpenID Connect. Machine to machine integrations exchange a client ID and secret for an access token, and send that token as a bearer token on every request.

Token endpoint

https://auth.ebx.energy/oauth2/token

Client auth

client_secret_basic · client_secret_post

Get a token

You need two things before your first call: credentials you create once, and a short-lived access token you exchange them for. No request works without the token.

1. 01

   Create client credentials

   In the Control Center under Organisation → Integrations, or via POST /v1/integrations, create a machine-to-machine integration and copy its client ID and secret. The secret is shown once; an integration holds two secrets at a time so it can be rotated without downtime.

   No Control Center access yet? Ask your EBX contact, or request test access for instant test credentials.

2. 02

   Exchange them for an access token

   POST the client_credentials grant to the token endpoint. Both client_secret_basic (shown) and client_secret_post are accepted.

   Token requestcURL

   curl -X POST "https://auth.ebx.energy/oauth2/token" \
     -u "$EBX_CLIENT_ID:$EBX_CLIENT_SECRET" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials"

   Token response200

   {
     "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjNiZTk...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "scope": "asset.read dispatch.read dispatch.write"
   }

3. 03

   Cache it and reuse it

   The token is valid for 60 minutes. Cache it and send it on every request until it expires, then exchange again. Don't request a token per call.

Call the API

Send the access token in the Authorization header. A token only ever reaches the assets of its own organisation. Every endpoint in the reference states the scope it requires: a valid token missing that scope is rejected with 403, a missing or expired token with 401.

curl "https://api.ebx.energy/v1/users/me" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

res = httpx.get(
    "https://api.ebx.energy/v1/users/me",
    headers={"Authorization": f"Bearer {token}"},
)
print(res.json())

const res = await fetch("https://api.ebx.energy/v1/users/me", {
  headers: { Authorization: `Bearer ${token}` },
});
const me = await res.json();

Errors & status codes →

Scopes

Scopes are granted per integration in the Control Center and returned on the token. What each group unlocks: