Skip to main content

OAuth 2.0 (client credentials)

The Energy Management API uses the OAuth 2.0 client_credentials flow. Every endpoint except GET /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 with 403 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-key header are rejected with 401; 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

Tokens expire after 3600 seconds (1 hour). Request a new token before the current one expires. You can also pass credentials via Authorization: Basic base64(client_id:client_secret) with grant_type=client_credentials in the body (RFC 6749).

3. Use the token

Pass the token as Authorization: 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

  1. Open Obtain an access token and click Try it.
  2. Enter your client_id and client_secret, keep grant_type as client_credentials, and send the request.
  3. Copy the access_token from the response.
  4. Open any endpoint page in the API Reference, paste the token into the Authorization field and send the request.
Requests from the docs go to the live production API and only reach your organisation’s locations. A 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.