Authentication

All EnergyCAP API requests require authentication. The API uses API keys passed via the ECI-ApiKey header.

Authenticating a Request

Add the ECI-ApiKey header to every request:

curl -X GET "https://app.energycap.com/api/v3/meter" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

The API key is a long encoded string that looks like this:

AWNhcHxUZXN0.bWNvcF9ldmVudHJvdXRlcnwxMDI0fDE1MzY=.C2RmN2YxZDYtODJhYi00MWYzLWEzYmUtZjdjNzYzZjUyMTgw

If authentication fails, the API returns 401 Unauthorized.

Creating an API Key

  1. Log in to EnergyCAP and navigate to API Keys and Webhooks
  2. Click Create API Key and provide a name and description
  3. Copy the key value when displayed — this is the only time you will see it

Create API key

Copy API key

Tip
Store your API key in a password manager or secrets vault immediately after creation. It cannot be retrieved later.

Required permission: The user creating the key must have Application Settings: Manage permission.

How API Keys Work

Permissions

An API key inherits all permissions from the EnergyCAP user who created it. If the user can access a resource in the EnergyCAP UI, the API key can access it via the API. If the user cannot, neither can the key.

This means you should create API keys from a user account with the appropriate level of access for your integration — not more, not less.

Identity

Actions performed with an API key are attributed to the owning user. For example, if a bill is created using an API key belonging to jsmith, EnergyCAP records jsmith as the creator.

Scope

An API key is scoped to the environment and datasource where it was created. A key created in the Implement environment will not work in Production, even if the datasource name is the same.

Created in Works in Production?
implement.energycap.com No
app.energycap.com Yes (US East Production only)
app-eu.energycap.com Yes (EU Production only)

Lifetime

API keys do not expire. They remain valid until explicitly deleted. Keep this in mind:

  • Deleting an API key immediately invalidates it — any integration using it will start receiving 401 errors
  • Deactivating the owning user has the same effect
  • There is no way to rotate a key — delete the old one and create a new one

Legacy Authentication

Older integrations may use the Authorization header with a bearer token:

Authorization: Bearer YOUR_TOKEN

This method is deprecated and will be removed in a future release. Migrate to ECI-ApiKey header authentication as soon as possible.

If both headers are present in a request, the API key takes precedence.

Security Best Practices

Practice Why
Always use HTTPS API keys are sent in headers — without TLS they are transmitted in plain text
Store keys in a secrets manager Never hardcode keys in source code or commit them to version control
Use least-privilege accounts Create keys from user accounts with only the permissions your integration needs
Audit your keys regularly Remove keys that are no longer in use
One key per integration If you need to revoke access for one system, you won’t break others

Troubleshooting

Error Cause Fix
401 Unauthorized Missing, invalid, or deleted API key Verify the key exists and is correct
401 Unauthorized The owning user has been deactivated Reactivate the user or create a new key under an active user
401 Unauthorized Key used in wrong environment Create a key in the correct environment (see Environments)
403 Forbidden The owning user lacks permission for the resource Update the user’s permissions in EnergyCAP