Quickstart Guide
================

In order for you to integrate eMSP functionality provided by be.Energised
into your system, we provide you with this resource based API.

Authentication
--------------

The API uses OAuth 2.0 `bearer tokens <https://datatracker.ietf.org/doc/html/rfc6750>`_,
issued by ChargePoint's Identity Management Service (IMS) using the
`client credentials grant <https://datatracker.ietf.org/doc/html/rfc6749#section-4.4>`_.
You authenticate with the `client_id` and `client_secret` you received from
us, and exchange them for a short-lived access token. That access token is
then sent with every subsequent API call.

.. note::
   The exact token endpoint URL for your account is also shown in your
   be.ENERGISED backoffice, under **Settings > API > eMSP API**.

.. rubric:: Step 1: Request an access token

Send a ``POST`` request to the token endpoint:

.. code-block:: text

  https://auth-eu.chargepoint.com/oauth2/token

Authenticate the request using **HTTP Basic Authentication**, where:

- the **username** is your `client_id`
- the **password** is your `client_secret`

and include `grant_type=client_credentials` either as a query parameter or
in the request body (both are accepted).

Sample request. Replace `CLIENT_ID` and `CLIENT_SECRET` with the values you
received from us:

.. code-block:: bash

  curl --location --request POST 'https://auth-eu.chargepoint.com/oauth2/token?grant_type=client_credentials' \
    --user 'CLIENT_ID:CLIENT_SECRET' \
    --header 'Content-Type: application/x-www-form-urlencoded'

.. rubric:: Step 2: Read the access token from the response

On success, IMS responds with a JSON body:

.. code-block:: json

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

- `access_token` is the bearer token you'll use to call the eMSP API.
- `expires_in` tells you how many seconds the token stays valid (around
  **2 hours**). Always read this value from the response rather than
  assuming a fixed duration — once it expires, simply repeat Step 1 to get
  a fresh one; there is no separate "refresh token" step.

.. rubric:: Step 3: Call the eMSP API with the access token

Include the access token in every eMSP API request, in the `Authorization`
header, prefixed with `Bearer`:

.. code-block:: text

  Authorization: Bearer <access_token>