Getting Started

This API is a user-based API, which means that all the data you can retrieve or send via the API is somehow connected to an existing user. Let’s say a user wants to find all available charging stations within a 5-kilometer radius and wants to then charge their vehicle at one of these charging stations. There are a few preconditions required to make this work, such as being an active user, having a valid contract for the station and the user’s preferred method of paying for the charging session. See below for information on the steps required to make this work.

The technology behind this API is GraphQL. GraphQL is an API query language for fulfilling queries with existing data. GraphQL provides a complete and understandable description of the data in your API, giving clients the power to ask for exactly what they need and nothing more.

Authentication

The first step in using this API is to understand the authentication mechanism. Valid authentication tokens are a prerequisite to gain access to the API. There are two options for acquiring these tokens.

Auth0

If the Auth0 feature is enabled for you, an application can use Auth0 to authenticate users. Assuming you have successfully authenticated with Auth0, you will have an access token. This access token can be used as an authorization bearer token in order to get access to our GraphQL API. An access token has a lifetime of 60 minutes - so if a user session takes longer than 60 minutes, you will have to reauthenticate with Auth0 to get a new access token. For more information on Auth0, please refer to the Auth0 documentation.

Pre-shared Key (PSK)

We recommend the Auth0 approach but there is also a legacy method provided for authorization.

First of all, you need a PSK, which can be created for your client in the GraphQL settings section of the be.ENERGISED backend. This PSK is used to confirm that a request (application) is allowed to access the API. The initial login request to start a user session should be successful (initSession). When you begin a session, two tokens will be issued: a session token and a refresh token. For all requests (e.g cpsPaged), the session token has to be stated in the request header as an authorization bearer token.

After 60 minutes, the session token expires and a new session token has to be retrieved. This can be accomplished by using the endpoint refreshSession and submitting the previously issued refresh token instead of the session token in the authorization header. A new session token and refresh token will be generated and provided to the client in the response.

Here is an example curl request to better understand the authorization process:

curl --location --request POST 'https://url-for-api' \
--header 'Authorization: Bearer your-api-token' \
--header 'accept-language;' \
--header 'Content-Type: application/json' \
--data-raw 'mutation{
              initSession(username: "demo-user",password:"demo-user-password")
              {
                sessionToken
                refreshToken
              }
            }'