Create a client app

✓ EnergyID for Business

Are you building an application where users sign in with their EnergyID account and give your app access to their data? Then you register an OAuth client app. Your app only gets the access the user consents to.

Do you only need access to your own data or to one Workspace? Then an API key is simpler. Read Authentication methods to choose the right method. An overview of the Web API is available in the API documentation.

Register your application

If you want to use the EnergyID Web API or distribute your Incoming Webhook as an app, first register your application. You do this by sending us an email with the following information:

  • application name;
  • an icon for the application;
  • URL to the application's home page;
  • a short description of the application;
  • a link to the application's privacy policy;
  • a list of redirect URLs;
  • a list of required scopes.

After registration, you receive a client ID and a client secret.

Go through the OAuth 2.0 flow

The EnergyID Web API uses the OAuth 2.0 protocol for authentication and authorization. All client apps follow the same basic pattern in four steps:

  1. Obtain OAuth 2.0 credentials.

    Register your app to obtain a client ID and client secret.

  2. Obtain an access token from the EnergyID Authorization Server.

    Before your application can access private data through the Web API, it must obtain an access token. The scope parameter determines which objects and actions the access token grants access to.

    First request an authorization code. Call GET https://identity.energyid.eu/connect/authorize with the following parameters:

    • client_id - issued when you registered your app
    • scope - the requested permissions, separated by spaces
    • response_type - should be set to code
    • redirect_uri - the callback URL that receives the authorization code
    • state - unique string passed back upon completion (optional)
    • ui_locales - the preferred display language of the login and consent screen, for example en-GB or nl-BE (optional)

    The user signs in with their EnergyID account and is then asked whether they want to grant the requested permissions. If the user consents, the Authorization Server sends an authorization code together with the granted scopes to your redirect URL. If the user refuses, you get an error back.

    Exchange the authorization code for an access token by calling POST https://identity.energyid.eu/connect/token with:

    • client_id - issued when you registered your app
    • client_secret - issued when you registered your app
    • grant_type - should be set to authorization_code
    • code - the authorization code from the previous step
    • redirect_uri - the same redirect URL as in the authorize call

  3. Send the access token to an API endpoint.

    Include your access token in the headers of every Web API request:

    Authorization: bearer {AccessToken}

  4. Refresh the access token if necessary.

    Access tokens have limited lifetimes. With a refresh token, your app requests a new access token without the user having to sign in again. Call POST https://identity.energyid.eu/connect/token with:

    • client_id - issued when you registered your app
    • client_secret - issued when you registered your app
    • grant_type - should be set to refresh_token
    • refresh_token - the refresh token you received along with the access token

Request the right scopes

Request only the scopes your app really needs. Users consent more readily when they understand why your app asks for certain access.

  • Most apps for individual users only need profile:read and records:read, or records:write if they need to change data.
  • Apps that work with Workspaces request workspaces:read or workspaces:write.
  • Add offline_access if your app needs a refresh token.

The full list of scopes is in the API documentation.

FAQ

Do I need to register an app if I only use an API key?

No. Registration is only needed for OAuth client apps. You create a personal or Workspace API key yourself in EnergyID. Read Authentication methods.

Why don't I get a refresh token?

You only receive a refresh token when you include the offline_access scope in the authorize call.