Getting Started with the Smart Charging Algorithm API

The Smart Charging Algorithm API provides access to the algorithm that can optimise a number of vehicle-charger pairings based on certain input parameters such as the maximum limit (kW) of a site, the specifications of the chargers and the vehicles. The result is a charging schedule for the vehicles.

This API is the entry point to the Smart Charging Algorithm. In a nutshell, given a charging site with a number of vehicle-charger pairings and their specifications (maximum site capacity kW, charger limits, vehicle charging limits etc) then the algo should return an optimal charging schedule to meet the requests of the vehicles. This schedule essentially is an instruction for a certain rate at a specific time period for a every vehicle.

This API product consist of 2 end points.

Authentication

Shell API’s are secured by OAuth 2.0. It uses the 'Client Credentials' Grant Type to allow the API consumer to access data. The end to end process is illustrated in the sequence diagram below.

Steps

1. Request Client ID and Secret

Contact Shell API Team in order to request access to OAuth authentication.

2. Generate and provide Client ID and Secret

Shell API team will generate the credentials and you will be intimated via email with all the details.

3. Request Access Token

Once you receive the credentials next step is to call the /token.oauth2 endpoint to authenticate. Below are the key parameters.

Key request parameters

Sample request

curl --location --request POST 'https://api-test.shell.com/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

4. Get an access token

On receiving the request Shell Authorizaton system will verify all the parameters in the request and, if everything checks out, it will generate your access token and return it in the response.

Key response parameters

The response will contain the following parameters:

Sample response

{
    "access_token": "**************",
    "expires_in(seconds)": "899",
    "token_type": "BearerToken"
}

Note: Make a note that the expires_in is always in seconds.

5. Call the Functional API

While calling Shell API’s include the following in the header of the request. Note the space after Bearer.

Authorization: "Bearer " + access_token

Note: This endpoint doesn't return refresh token. Hence in case the bearer token expires the same endpoint should be called to retrieve new bearer token

Troubleshooting authentication

The following table lists common authentication errors and possible causes:

All error scenarios are returned with a response body and identifier. Few examples below for

Example 1 : HTTP 400 - Bad Request

{
      "ErrorCode": "invalid_request",
      "Error": "Unsupported grant type : client_credential"
}

Example 2 : HTTP 401 - Unauthorized

{
    "ErrorCode": "invalid_client",
    "Error": "ClientId is Invalid"
}