Skip to main content

EnergyZero Public Facing APIs

This section describes all the public-facing APIs provided by EnergyZero. These APIs allow external systems and applications to interact with the EnergyZero platform, enabling a wide range of integrations and functionalities.

Getting Started​

All EnergyZero APIs are secured using JSON Web Tokens (JWTs).

What is a JWT?​

A JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs are commonly used for authentication and authorization.

EnergyZero Identity Provider (IDP)​

JWTs for accessing EnergyZero APIs are issued by the EnergyZero Identity Provider (IDP). The IDP is a centralized service responsible for managing user identities and issuing security tokens. It acts as the trusted authority that authenticates users and applications, and then grants them access to protected resources (our APIs).

Obtaining a JWT​

There are two primary flows to obtain a JWT from the EnergyZero IDP:

  1. Login Flow (Authorization Code Grant): This flow is typically used for user-facing applications where a user interacts with a login interface. After successful authentication (e.g., username and password), the IDP issues a JWT to the application, which can then be used to make API calls on behalf of the user.

  2. Client Credentials Flow: This flow is used for machine-to-machine communication, where an application needs to access APIs without a user's direct involvement. The application authenticates itself to the IDP using its client ID and client secret, and the IDP then issues a JWT directly to the application.

API Permissions and Audiences​

To ensure selective permissions and granular control over API access, most EnergyZero APIs require a specific audience claim within the JWT. The audience claim identifies the intended recipient of the JWT and the resource it is meant to access.

For example, an API related to customer management might require an audience of customer-api, while an API for energy data might require energy-data-api.

The only exception to this rule is the Public API, which does not require a specific audience claim.

Granting Audiences: Access to specific audiences is managed by an EnergyZero administrator. If your application requires access to a particular API, an EnergyZero administrator will need to grant the necessary audience permissions to your user or client credentials within the IDP.

API Documentation Structure​

This section will provide detailed documentation for each public-facing API, including:

  • Endpoint URLs
  • HTTP Methods
  • Request Parameters
  • Request Body Schemas
  • Response Body Schemas
  • Authentication Requirements
  • Example Requests and Responses

Please navigate through the sidebar to explore the documentation for specific APIs.