Skip to main content

Get started

Authentication

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.

OAuth Flow

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-

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"
}
HTTP Code Description Scenarios
400 Bad Request If Invalid scope passed to Token url
Invalid grant type passed to Token url
401 Unauthorized If Invalid id/secret passed to Token url
If Invalid or expired token passed to destination system’s API

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

About us

The Shell Developer Portal is here to support partners to onboard to Shell APIs, the portal is here to take ideas to production

 

Shell logo

Login to your account