Authentication methods

You can authenticate with the EnergyID Web API in three ways. Which method you choose depends on who owns the integration and on whose behalf it requests data. With the right choice, your integration gets exactly the access it needs and stays manageable in the long run.

An overview of the Web API, scopes and object models is available in the API documentation. All endpoints are listed in the API reference documentation.

Choose the right method

OAuth 2.0 for client apps

Use OAuth when your application acts on behalf of users who sign in with their own EnergyID account and give your app consent. Typical use cases:

• web or mobile apps where users sign in themselves;
• apps for multiple customers, with consent per user;
• flows where the user grants and revokes access themselves.

Read Create a client app to register your app and go through the OAuth flow.

Personal API keys

Use a personal API key for your own scripts, prototypes and small automations. The key belongs to your account and grants access to your profile and your records. Typical use cases:

• exporting your own data;
• command-line tools for one user;
• temporary scripts.

Workspace API keys

Use a Workspace API key for backend integrations owned by an organization or energy community. The key belongs to the Workspace rather than to a person, so the integration keeps working when its creator leaves the organization. Typical use cases:

• data warehouse synchronization;
• scheduled Workspace reporting;
• server-side integrations that should not depend on one person.

Workspace API keys are available from the Standard plan. How to create, rotate and delete them is explained in API keys for Workspaces.

Building an organization-owned integration that runs in production? Choose a Workspace API key rather than a personal API key.

Create a personal API key

You create a personal API key in your account settings:

• Open your user menu and click Settings.
• Go to Developersettings.
• Under API keys, click Generate key.
• Choose Read or Read & write.
• Click Create.

You delete a key you no longer use in the same place.

Note: a personal API key grants access to your entire account. Store the key securely and delete it immediately if it becomes public.

Scopes and access levels

Personal API keys

A personal API key gets scopes for your profile and your records. Your choice at creation time determines whether the key can also write.

Workspace API keys

A Workspace API key gets scopes for the Workspace and for records. The access level you choose at creation time determines the key's scopes and Workspace role.

• Viewer (workspaces:read, records:read): read-only access to all records in the Workspace.
• Contributor (workspaces:write, records:write): add meter readings and register timeline events in all records in the Workspace, otherwise read-only access.
• Editor (workspaces:write, records:write): edit all records in the Workspace, without managing access rights or changing Workspace settings.

The key grants access to the Workspace endpoints of that one Workspace, and to the record endpoints for internal records, meaning records owned by the Workspace. External records can only be reached through the Workspace endpoints.

OAuth apps

An OAuth app requests the scopes it needs itself, including Workspace scopes. The user sees those scopes when they give consent. The full list of scopes is in the API documentation.

Send your key with an API request

Send your API key in the Authorization header, preceded by the word apikey. This applies to both personal and Workspace API keys.

Authorization: apikey YOUR_API_KEY

Note: do not use the Bearer format for an API key. That format is reserved for OAuth access tokens (Authorization: bearer {AccessToken}). An API key sent as a bearer token is rejected with 401 Unauthorized.

Example with a Workspace API key: list the records of a Workspace. You find the Workspace ID in the address bar when you open the Workspace in the app: https://app.energyid.eu/w/<workspace-id>/....

curl "https://api.energyid.eu/api/v1/Workspaces/<workspace-id>/records" \
  -H "Authorization: apikey YOUR_API_KEY"

Example with a personal API key: list your own records. me refers to your own account, so you do not need a user ID.

curl "https://api.energyid.eu/api/v1/Members/me/records" \
  -H "Authorization: apikey YOUR_API_KEY"

Which other endpoints exist and which parameters they accept is described in the API reference documentation.

FAQ

Which method should I choose for a backend integration that syncs data for one Workspace?

Use a Workspace API key. It belongs to the Workspace, keeps working when its creator leaves, and only grants access to that one Workspace.

Can I use a personal API key for my team's integration?

We do not recommend it. A personal API key is tied to one user account and grants access to that entire account. That makes it hard to manage when several people are responsible for the integration.

My request with an API key returns 401 or 403. What is wrong?

With 401 Unauthorized, the key is not recognized. Check that the header starts with apikey and not with Bearer, and that the key has not been deleted. With 403 Forbidden, the key is recognized but lacks the rights for that action, for example a key with the Viewer access level that tries to change data.

Do I still need OAuth if I already use API keys?

Yes, for apps where users sign in themselves and give your app consent. For those apps, OAuth remains the right method.