Loyalty APIs Authentication Guide

The Loyalty APIs use the OAuth2 authorization code grant type to obtain permission from a Shell GO+ customer to perform a specific action on their behalf, such as:

• Viewing, adding, or redeeming loyalty points
• Providing a purchase discount (such as 10% off fuel)

This method enables your application to perform these actions without having to know the customer’s password. Instead, your application authenticates with a time-sensitive access token.

The following sequence diagram illustrates this process:

This is the sequence of steps when a user visits your application:

1. Your application redirects the customer’s browser to the Shell authorization server.
2. The customer logs into an existing Shell GO+ account (or registers for a new one) and provides consent for the operation that your application wants to perform on their behalf.
3. When the customer has provided the required consent, the Shell authorization server makes a request to an endpoint that your application provides. This is your redirect URL. The response body contains an access code and the user's unique identifier.
4. Your application makes a further request to the Shell authorization server to exchange the access code for an access token.
5. Your application then uses this access token to make requests to the Loyalty APIs on the customer’s behalf.

Before you begin

Contact Shell for access to the Loyalty APIs. The Shell team will provide you with a Client ID and API key via email that you can use to authenticate with.

They will also set up your redirect URLs. These are your application endpoint URLs that the Shell authorization server can POST the access code to. You might choose to have separate URLs for development, testing, and production. Shell will whitelist the base URL to enable you to use any of these endpoints.

Steps

1. Begin authentication

Use a POST request to get a basic public token from the Shell Identity API.
Note: The body of the request must contain your SH256-encrypted Client ID. For example, typically formed using the javascript notation:

var digest = CryptoJS.SHA256(user_clinetID).toString();

Key request parameters

Sample request

curl --location --request POST 'https://test.id.consumer.shell.com/api/v2/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "digest": "******************"
}'

Sample response

{
    "token": "**********",
    "tokenType": "Basic",
    "expiresIn": "unlimited",
    "owner": "partner_1"
}

2. Request user permissions

To act on behalf of the user and satisfy the OAuth flow, you need the user to sign into their Shell GO+ account. Once they have signed in, your application redirects the user to the Shell login page with the appropriate query parameters set in the SSO Widget:

https://test.login.consumer.shell.com/?market=<country-code>&partner=true&clientId=<client-id>&redirect=<redirect-url>

The query parameters you must supply are:

• market: A combination of language code (lower case) and country code (upper case), separated by a hyphen. For example: en-BG.
• clientId: unique Shell client ID of the partner. Same key passed previously to get the public token.
• partner: true (default for any customer).
• redirect: Your application redirect URL.

Notes:

• the redirect url test.shell.com needs to be white listed by Shell.
• always use a unique id as part of the redirect url to maintain the conversation state and ensure session tracking, rather than rely on cookies.
  For example test.shell.com/session=1452923773

Once signed in, the Shell SSO login redirects to the application URL specified in the redirect parameter. The URL contains a query parameter specifying the access code. See the code line below.

Note: the accessCode is only valid for 30 secs.

https://<your-redirect-url>?accessCode=****************

3. Access user details

To get the user's unique ID (UUID) and authorization token from the /auth/exchangeAccessCode endpoint, use the access code from step b together with the basic public token you retrieved in step a.

Key request parameters

Now to exchange the accessCode for an access token, for example:

Sample request

curl --location --request POST 'https://test.id.consumer.shell.com/api/v2/auth/exchangeAccessCode' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic **************' \
--data-raw '{
  "accessCode": "**************"
}'

Sample response

{
    "uuid": "********************",
    "market": {
        "code": "en-BG",
        "country": "BG"
    },
    "accessToken": "**********",
    "refreshToken": "**********"
}

Note: Make a note of the following values in the response:

• uuid: This is the customer's unique ID. This is referred to as the <consumerUUID> in later steps.
• accessToken: This is referred to as the <user-authorization-token> in later steps. Note, this is valid for 20mins.
• refreshToken: A refreshToken is available for the <user-authorization-token>. Refer to Step 6 for details. In the response above the field refreshToken is used to get new accessToken via the endpoint:

  https://test.id.consumer.shell.com/api/v2/auth/token/refresh.

  4. Get an access token

Obtain an API gatewway access token by making a POST request to the Shell Authentication OAuth endpoint

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'

Sample response

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

Note: Make a note of the accessToken in the response. This is the system to system token referred to as the client-authorisation-token in later steps.

Note: The Access Token in this example is valid for 899s.

5. Make a Loyalty API request

Now, we have all the necessary user and client authorization tokens in order to proceed with the functional Loyalty APIs like Assign offer, Check balances and so on. Refer to the documentation for the specific API you are working for full details.

Refresh User Authorization Token

With the refresh token provided when exchanging the accessCode, a new access token (user-authorization token) can be generated.

Key request parameters

Sample request

curl --location --request POST 'https://test.id.consumer.shell.com/api/v2/auth/token/refresh' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ****************' \
--data-raw '{
  "refreshToken": "************"
}'

Sample response

{
    "accessToken": "***********",
    "refreshToken": "***********",
    "expiresIn": 3300
}

Troubleshooting authentication

The following table lists common authentication errors and possible causes: