Automated API Access

This article explains how to use the Energyworx APIv1.5. This way you can use it for simple calls from your laptop or for any complex integration you may require. Here we'll explain how to authorize yourself or your applications to talk to the API, including some examples in Python.

Authorized requests

In order to make an authorized call to the API you need 2 elements in the header of each request.

• X-NAMESPACE
• Authorization

Authorization header

For authorization, you use a Bearer token in the Authorization header. There are two ways to obtain one:

• Client credentials (recommended): exchange a client ID and secret for a short-lived access token. This is the way to go for scripts and application integrations, and is explained in detail below.
• Browser session token: the token exchanged between your browser and the platform on console interactions. Handy for quick manual calls, but it expires with your session and is not suitable for automation.

Client credentials

Client credentials are the recommended way to authenticate automated access to the API. You create them yourself in the platform UI, and the secret never leaves your hands — you never need to share any sensitive material with Energyworx.

Note: client credentials are created per environment (aka project), not per namespace.

1. Create a credentials pair

1. In the platform UI, go to Settings → Automated access.
2. Give the credentials a recognizable display name and remember it — you will need it later to identify this pair, for example in a service desk ticket.
3. Choose an expiry. Credentials can be valid from 1 hour up to 1 year.
4. Create the pair. The client ID and client secret are shown only once — store them in a secure place (for example a secrets manager). If you lose the secret, create a new pair; the old one remains valid until it expires. To have it revoked earlier, create a ticket for the service desk.

2. Bind the credentials to a service account

Newly created credentials act on behalf of the user who created them. For application integrations you typically don't want access tied to a personal account — instead the credentials should act as a designated service account.

To arrange this, create a ticket for the service desk stating:

1. The display name of the credentials pair you created.
2. The service account email the credentials should act as.

Do not include the client ID or client secret in the ticket — Energyworx never needs them. Once the service desk confirms the change, tokens issued for your credentials act as the service account.

3. Request an access token

Exchange the client ID and secret for an access token using the token endpoint of the environment:

POST https://identity.[environment].ewxapis.com/oauth2/v1/token

import requests

response = requests.post(
    "https://identity.[environment].ewxapis.com/oauth2/v1/token",
    headers={"Content-Type": "application/json", "accept": "application/json"},
    json={
        "grant_type": "client_credentials",
        "client_id": "[your client ID]",
        "client_secret": "[your client secret]",
    },
)
response.raise_for_status()
token_response = response.json()

access_token = token_response["access_token"]  # use as Bearer token
expires_in = token_response["expires_in"]      # validity in seconds

Access tokens are short-lived; the expires_in field tells you how many seconds the token remains valid. Incorporate the token generation into your script and request a new token before the current one expires, rather than generating one manually for each session.

4. Call the API

Use the access token as the Bearer token in the Authorization header, together with the X-NAMESPACE header.