Skip to main content

Shell Authentication 1.0.0

This API enables an application to authenticate with a time-sensitive access token as part of the OAuth Authorisation flow.

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.

sequenceDiagram participant PartnerApplication participant Shell autonumber alt Manual Process rect rgb(200, 150, 255) PartnerApplication ->>Shell: Request Client ID and Client Secret activate Shell Shell ->> PartnerApplication : Generate and provide Client ID and Client Secret deactivate Shell end end alt Authentication/Authorization rect rgb(191, 223, 255) PartnerApplication ->>Shell: Inititate request to OAuth end point with credentials activate Shell Shell ->> PartnerApplication : (200-OK) Returns Bearer Token deactivate Shell end end alt Call Functional Endpoint rect rgb(200, 150, 255) PartnerApplication ->>Shell: Initiate request to functional endpoint along with bearer token received from previous step activate Shell Shell ->> PartnerApplication : Returns a response on validation of the bearer token deactivate Shell end end

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

Element Value
Method POST
Endpoint /v1/oauth/token
Headers Content-Type: application/x-www-form-urlencoded
Body _clientid: **********
_clientsecret: *********
_granttype: client_credentials

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:

Element Value
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

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:

HTTP Status Code Value Possible causes
400 Bad request Missing or incorrect parameters or header values
401 Unauthorized
  • Invalid Client ID or API key
  • 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"
    }

    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