Quickstart Guide

Learn how to get started quickly with the be.ENERGISED CPO API.

The following sample will show you:

• How to authenticate against the API
• How to fetch a list of charging stations available for your token

For this example we have the following expectations:

• You already know how to use REST APIs and have seen basic concepts of jsonapi.org
• You received an API token which has at least one scope starting with cpoapi (if your license allows this you can create one in the be.ENERGISED ui under Settings -> CPO API. This might come with additional costs depending on your license).

Authentication

The API uses bearer tokens, which can be fetched on the endpoint https://beenergised-jwtapis.auth.eu-central-1.amazoncognito.com (see example curl request). The initial token fetching requests contains a client_id and a client_secret.

The response of this first request (json response) is an access token. This access token must then be included in calls against the endpoint of your mandant.

Sample request to receive the bearer token. CLIENT_ID and CLIENT_SECRET must be exchanged with your received client_id and client_secret.

curl --location --request POST 'https://beenergised-jwtapis.auth.eu-central-1.amazoncognito.com/token?grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET' \
  --header 'Content-Type: application/x-www-form-urlencoded'

The response will look similar to the following:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "expires_in": 86400,
    "token_type": "Bearer"
}

The field access_token must then be included in all further requests with the header Authorization: Bearer <access_token>. Also keep an eye on the expires_in field. This field gives you a hint, how long your token can be used before you have renew it.

Fetch a list of charging stations

In order to fetch the charging stations you need to first fetch the bearer token (as described before). The received access token must then be added to the request header (Authorization). The charging stations can then be fetched with:

curl --location --request GET 'https://yourmandant.beenergised.cloud/api/cpoapi/v1/charging_stations/' \
--header 'Authorization: <access_token>'

This will result in a json response. The json response contains a data attribute with the entries. The response will automatically take into account your token restrictions. If the token is bound to a certain entity in the be.ENERGISED system, you will only receive stations which are available for that entity. The response also contains a pagination information, so that you can continue to read further pages (if there are some).

Sample response:

"data": [
    {
        "type": "charging_stations",
        "id": "a1123a54-ef49-4e52-9465-2ac2dc100f2e",
        "attributes": {
            "label": "Station 1",
            "chargeBoxIdentity": "cp_1",
            "iccid": "12345",
            "imsi": "567869",
            "serialnumber": "112233",
            "firmwareVersion": "htb.firmware.version"
        }
    }
],
"meta": {
    "pagination": {
        "total": 10,
        "offset": 0,
        "limit": 1,
        "lastPage": false
    }
},
"links": {
    "current": "https://slug.beenergised.cloud/api/cpoapi/v1/charging_stations/?page%5Blimit%5D=1&page%5Boffset%5D=0",
    "next": "https://slug.beenergised.cloud/api/cpoapi/v1/charging_stations/?page%5Blimit%5D=1&page%5Boffset%5D=10"
}