OAuth 2.0 (client credentials)
The Energy Management API uses the OAuth 2.0 client_credentials flow. Every endpoint exceptGET /health and POST /oauth/token requires a
Bearer token:
1. Create credentials
Any user of your organisation can create OAuth client credentials in the RiDERgy dashboard: open My account and go to OAuth Clients, then Create new client. RiDERgy has to enable the Energy Management API for your organisation first; without it, requests fail with403 FEATURE_NOT_ENABLED.
- Client ID (
emcl_...): not secret. It stays visible in the dashboard. - Client secret (
emcs_...): shown once, when you create the client. Store it straight away in a password manager or secrets vault. RiDERgy cannot show it again; if it is lost, create a new client and revoke the old one. - Choose only the scopes your integration needs. New clients start read-only.
- A client belongs to your organisation, not to the person who created it, so it keeps working when that person leaves.
- RiDERgy does not issue API keys. Requests with an
x-api-keyheader are rejected with401; always use a Bearer token as described below.
No dashboard login yet? While your organisation is being onboarded,
RiDERgy can issue a temporary client that expires after 7 days. You will
receive the client ID and the secret through two separate channels. Once you
have a dashboard login, create your own client and ask RiDERgy to revoke the
temporary one.
2. Exchange for an access token
Authorization: Basic base64(client_id:client_secret)
with grant_type=client_credentials in the body (RFC 6749).
3. Use the token
Pass the token asAuthorization: Bearer <token> on every request:
- Your tenant is embedded in the token and cannot be spoofed — credentials for one tenant cannot access another tenant’s data.
- An expired or invalid token returns
401 UNAUTHORIZED. - A token missing a required scope returns
403 INSUFFICIENT_SCOPE.
Scopes
Tokens carry scopes that control which endpoints are accessible:
Requests to endpoints requiring a scope the token does not have will fail
with
403 INSUFFICIENT_SCOPE.
Testing in the docs
- Open Obtain an access token and click Try it.
- Enter your
client_idandclient_secret, keepgrant_typeasclient_credentials, and send the request. - Copy the
access_tokenfrom the response. - Open any endpoint page in the API Reference, paste the token into the Authorization field and send the request.
POST/PUT changes real charging limits, so test
with a read-only client unless you mean to apply the change.
Rotating and revoking credentials
- Rotate: create a new client, switch your integration to it, then revoke the old client.
- Revoke: in the dashboard, next to the client. Revocation takes effect immediately: tokens already issued to that client stop working on their next request.
- Expired temporary clients stop working the same way.

