Authentication

The API is protected by OpenID Connect. Machine-to-machine (M2M) 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

   Sign in to your account

   Sign in with your Control Center account, using email and password or Google SSO.

   Sign in

   No account yet? Contact operations@ebx.energy.

2. 02

   Create client credentials

   Create one integration per system that calls the API, and grant it only the scopes it needs. Creating an integration requires the clients.write scope. You can only grant scopes you hold yourself (verify them with GET /v1/users/me).

   To give a partner access to only some of your assets, add asset_ids to the request. The integration then reaches only those assets, and its scopes must be exactly asset.read. Any other asset answers 404.

   Example requestcURL

   EBX_USER_TOKEN="<user token from step 1>"
   INTEGRATION=$(curl -s -X POST "https://api.ebx.energy/v1/integrations" \
     -H "Authorization: Bearer $EBX_USER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-integration", "scopes": ["asset.read", "dispatch.read"]}')
   EBX_CLIENT_ID=$(echo "$INTEGRATION" | jq -r .integration_id)
   EBX_CLIENT_SECRET=$(echo "$INTEGRATION" | jq -r .client_secret)

   Example response201

   {
     "integration_id": "4kq1v2l9h8t3m5n7p0r6s2u8wx",
     "client_secret": "1m9c0f7e2d...",
     "name": "my-integration",
     "organization_id": "your-org",
     "scopes": ["asset.read", "dispatch.read"]
   }

   Store the integration_id (your client ID) and client_secret. The secret is shown only once. To rotate it, add a second secret, then delete the old one.

3. 03

   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.

   Example requestcURL

   EBX_ACCESS_TOKEN=$(curl -s -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" \
     | jq -r .access_token)

   Example response200

   {
     "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjNiZTk...",
     "token_type": "Bearer",
     "expires_in": 3600
   }

   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.

4. 04

   Call the API

   Send the access token in the Authorization header. It only reaches your own organisation's assets, and an integration created with asset_ids only the assets listed there. Each endpoint in the reference states the scope it requires: a token without it gets 403, a missing or expired one 401.

   Example requestcURL

   curl "https://api.ebx.energy/v1/assets" \
     -H "Authorization: Bearer $EBX_ACCESS_TOKEN"

   Errors & status codes →

Scopes

Scopes are granted per integration when you create it, and carried in its access token. What each group unlocks: