Loyalty APIs Authentication Guide

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/v2/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": "899",
    "token_type": "Bearer"
}

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"
}