Partner authentication

This document describes the process for partners to obtain an access token for the Energyzero Platform. With this access token you get access to all the API's which your credentials have the correct audience granted. The extend to which your access token has access to is configured by the platform team in Energyzero.

When using the OAuth2 client credentials grant, your application (the client) authenticates itself directly with the platform and receives an access token scoped to the partner level. This access token allows the application to perform actions and access resources within the partner scope, rather than on behalf of an individual user. Within this topology, multiple users or customers are associated with a single partner. Users can have different roles: some may be customers with contracts, while others may be colleagues in roles such as support, potentially with broader permissions than customers. Importantly, a user does not have to be a customer—they could simply be a staff member with elevated access. The following diagram illustrates the relationship:

+---------------------+
|      Partner        |
+---------------------+
         |
   +-----+-----+---------------------+
   |           |                     |
+------+   +----------+         +----------+
|User A|   |Customer B|         |Support C |
+------+   +----------+         +----------+
 (staff)    (customer)           (staff, more perms)

Environments

• Prerelease (Testing): https://auth.api.staging.energyzero.nl
• Production: https://auth.api.energyzero.nl

OAuth2 Client Credential Grant

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user. This is typically used by clients to access resources about themselves rather than to access a user's resources. This is the method chosen for partners to interact with the Energyzero platform.

Energyzero provides the client_id and client_secret to the partner through 1Password share 🔐. The access token gives access to one or multiple API's provided by Energyzero. The access token is valid for a single whitelabel partner and can be used to mutate and retrieve data for customers that belong to this whitelabel partner. Some API's are only meant to be used from the perspective of a User/Customer 👨 👩, so an impersonate is required.

Impersonation Flow

1. Use Provided Client Credentials
   The supplied client_id and client_secret are required to continue with the EnergyZero APIs.

2. Getting your credentials to impersonate
   Using the provided credentials, to perform the standard OAuth2 Client Credentials grant via your preferred way/tool (Postman has this feature built-in). The method for credential provisioning is by using credentials via FORM.
   Upon success, a valid JWT is returned in the Authorization header which is valid for 5 minutes.

   Example of the request:

      curl --location 'https://auth.api.staging.energyzero.nl/oauth2/token' \
      --form 'grant_type="client_credentials"' \
      --form 'scope="openid offline"' \
      --form 'client_id="<CLIENT_ID>"' \
      --form 'client_secret="<CLIENT_SECRET>"'

3. Request Impersonation for a Specific User
   With the token from step 2, call the impersonation endpoint.

   Field	Value/Description
   Endpoint	/v1/auth/impersonate
   Method	GET
   Headers	Authorization: Bearer <token from step 2>
   Query Parameters	user_id: The user ID to be impersonated

   If valid, a new JWT is issued which is valid for 1 hour for that specific user and can be retrieved through the Authorization header.

   Example of the request:

      curl --location 'https://auth.api.staging.energyzero.nl/v1/auth/impersonate?user_id=<user_id_belonging_to_your_partner_connection>' \
         --header 'Authorization: <Token from step 2>'

   Example of the response:

   {
   "access_token": "<CUSTOMER_ACCESS_TOKEN>",
   "expires_in": 3599,
   "scope": "openid offline",
   "token_type": "bearer"
   }

   4. Access the User/Customer perspective API
      You can now use the user impersonate token to call any Energyzero API on behalf of the impersonated user.

      Example of Customer API request:

      curl --location 'https://customer.api.staging.energyzero.nl' \
          --header 'Content-Type: application/json' \
          --header 'Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>' \
          --data '{"query":"query me{\n    me {\n        firstName,\n        surname\n    }\n}","variables":{}}'```