API Authentication

The EnergyCAP API considers all responses to be private, thus all API requests must be authenticated.

To authenticate an EnergyCAP API request, an API key must be sent via the ECI-ApiKey header. A sample API key header is represented below:

ECI-ApiKey: AWNhcHxUZXN0.bWNvcF9ldmVudHJvdXRlcnwxMDI0fDE1MzY=.C2RmN2YxZDYtODJhYi00MWYzLWEzYmUtZjdjNzYzZjUyMTgw

While legacy authentication methods continue to work (i.e use of the Authorization header with a bearer token), these methods are being deprecated and will stop working in the future. All new development targeting EnergyCAP APIs should authenticate with API keys instead. Additionally, if both an Authorization header and an ECI-ApiKey header are provided in a request, we will authenticate using the API key.

What are API Keys?

API keys are secret, lengthy, encoded strings which serve as substitutes for usernames and passwords and are intended for use by other software systems which integrate with EnergyCAP via its APIs.

Obtaining an API Key

API keys may be created in the “API Keys and Webhooks” view in EnergyCAP by a user who has Application Settings: Manage permission.

Create API key

When you create a new API key, provide a name and description. When you finish, you will see a one-time display of the secret API key value. This value is sensitive information and should be copied at creation and stored in a password manager or other secure location for future use:

Copy API key

API Key Lifetime

API keys never expire, which is why they must be secured and managed with care. However, they can be revoked by deletion. If an API key being used in another system is deleted, the EnergyCAP API will return a response having the HTTP status code of 401 Unauthorized. This status code is only returned 1) if an invalid API key is used or 2) the API key’s owner lacks permission to access the requested resource.

Please be aware that 1) deleting an API key which is used by another system or 2) deactivating the user who owns that API key could break those other systems!.

Also, an API key will only authenticate for the environment and datasource in which it was created. For example, an API key created in EnergyCAP’s Implement environment will not work in the Production environment, even if the datasource names are the same in both environments.

Permissions and Identity

Permissions are inherited from the EnergyCAP user who owns the API key. If a user has access to certain objects or actions in EnergyCAP, the API key will grant access to the same objects and actions via the API. Likewise, if the EnergyCAP user does not have access to an object or action in EnergyCAP, the API key will not grant access to that object or action.

Identity is another aspect of this inheritance: if an action is performed using an API key, then it will appear as if the EnergyCAP user performed that action. For example, if a bill is created using an API key belonging to user jsmith via the Create Bill API, then the new bill will display jsmith as the creator.

It is strongly recommended that SSL be enabled on your web server before using the API. Doing so will protect credentials and response data as it is requested from the API. Without SSL enabled on the web server, using the EnergyCAP APIs will transmit your API key in plain text which poses a security risk.

If your company does not maintain valid SSL certificates that are readily available to use, we strongly encourage you to investigate the Let’s Encrypt initiative - a secure, freely available Certificate Authority (CA) to enable SSL for your website.