Get started

OAuth 2.0 Authentication

Most of Shell API’s are secured by OAuth 2.0. This guide is for all Shell APIs that are following the standard Oauth flow. 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.

This step is to generate the API Access Token using the unique Client ID and Client Secret provided by Shell. (Please note that this credentials is to validate the API request between Shell and its partner so its system to system access token)

Key Request Parameters

Once you receive the client ID & Secret, next step is to call the https://api-test.shell.com/v2/oauth/token endpoint to authenticate. Following are the key parameters-

• Method: POST
• Authorization Type: OAuth 2.0
• Auth URI: https://api-test.shell.com/v2/oauth/token
• Client_Id: **** (OAuth Client ID)
• Client Secret: **** (OAuth Client Secret)
• Grant Type: client_credentials

Sample cURL 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'

On receiving the request Shell Authorization 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.

Sample Response

{
    "access_token": "***********",
    "token_type": "Bearer",
    "expires_in": 7199
}

The response will contain the following parameters:

• access_token: The token to be used to call the functional APIs
• expires_in: The amount of seconds until the access token expires.
• token_type: Bearer

Exception Handling

All error scenarios are returned with a response body and identifier.

{
      "error_descrription": "invalid client or client credentials",
      "error": "invalid_client"
}

Basic Authentication

Some of Shell APIs are authorized with an API key and HTTP Basic Authentication. A customer is identified as an API client and is provided a unique API key and secret for each of the supported environments.

All Shell API endpoints require the default authorization header including the target host, apikey and a base64 encoded Authorization header. The Authorization header contains the word Basic followed by a base64 encoded value of apiKey:secret.

For example:

Host: api-test.shell.com/test
Content-Type: application/json
Authorization: Basic RXZyQWhTeFpYcDhRQVBSSUp2bmthOnNlY3JldA==
apikey: EvrAhSxZXp8QAPRIJvnka