Authentication
Send your API key in the Authorization header of every request, as a bearer token:
Authorization: Bearer <your API key>curl "https://api.energi.ai/v3/company" -H "Authorization: Bearer $ENERGI_API_KEY"curl "https://api.us.energi.ai/v3/company" -H "Authorization: Bearer $ENERGI_API_KEY"Always call the API over https://. A plain http:// request is redirected to HTTPS, but only after it has sent your key unencrypted.
What is checked on every request
- The key: it must exist, be unexpired and not be revoked.
- The company in the path (
/v3/company/{companyId}/…): it must be one of the key’s companies, and the key’s creator must still be an Admin or Owner there. - The scope: the key must have the scope the operation needs, and the company’s plan must include what it does. Each operation’s scope is listed in Get access and in the API reference.
The checks use the key’s and its creator’s current state, not the state when the key was created: revoking a key, or its creator losing the Admin role, applies to the requests that follow.
401 or 403
| Status | Means | What to do |
|---|---|---|
401 UNAUTHORIZED | The Authorization header is missing or malformed, or the key is unknown, expired or revoked. | Check the header, and that the key is Active on the API keys page. Don’t retry with the same key. |
403 FORBIDDEN | The key is valid, but not for this request: the company isn’t one of its companies, its creator isn’t an Admin or Owner there, the key lacks the scope, or the company’s plan doesn’t include it. | Check the key’s companies and scopes on the API keys page, and the creator’s role. Don’t retry until one of them changes. |
Neither error says which check failed, so that a key’s details never leak to whoever holds it. Both bodies follow the format in Errors and limits.
Finding the company id
Every operation except the company list takes a company id in its path. Get it from GET /v3/company (scope company:read), which returns every company the key can access with its id, name and orgNumber. Store the id as a string: see Ids.