Loyalty Account Management 2.6.2

Loyalty APIs Authentication Guide

The Loyalty APIs use the OAuth2 authorization code grant type to obtain permission from a Shell 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.

Details of Loyalty Tokens

Basic Public token for SSO Endpoints

SSO Access Token OR User Authorization token

OAuth token for client-authorization-token

You can cache the user authorization token and client authorization token so that your application only requests a new token if a cached token is expired. Otherwise, the API endpoint returns the token from the cache.

The default expiration time mentioned in the above table is for reference only. You must refer the API response for the actual expiration time of the token.

Sequential Flow

The following sequence diagram illustrates the step by step authentication process:

Sequences followed when a customer visits your application

1. The user initiates a request in your application.
2. Your application requests Basic Public token from Shell Identity API when the user initiates a request.
3. Your application redirects the user's browser to the Shell authorization server.
4. The user logs into an existing Shell account (or registers for a new one) and provides consent for the operation that your application wants to perform on their behalf.
5. When the user 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 query parameter in the redirect URL contains an accessCode as seen here - *https://?accessCode=**.
6. Your application makes a further request to the Shell authorization server to exchange the access code for an accessToken (user-authorization-token)
7. Your applications makes a request to Shell's API Management Gateway (OAuth Authentication) to obtain client-authorization-token.
8. Your application then uses the user-authorization-token and client-authoriz ation-token along with Customer UUID 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 provides you with a Client ID from Shell Single Sign on and a Client ID and Client Secret from Shell's API Management Gateway via email that you can use to authenticate with.

The Shell team 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 whitelists 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_clientID).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 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 OR Shell Single Sign on Client ID. Same key passed previously to get the public token.
• partner: true (default for any customer).
• redirect: Your application redirect URL.

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. Get User Authorization Token using Access Code

To get the user's unique ID (UUID) and user 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 55 mins (3300 secs). Note that you must refer the API response for the actual expiration time of the token.

• 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 a Client Authorization Token from Shell's API Management Gateway

Obtain an API gateway access token by making a POST request to Shell Authentication OAuth ({{Shell Environment URL}}/v2/oauth/token) endpoint. The obtained Oauth token is passed to the Authorization header as a Bearer token when you invoke any functional loyalty APIs.

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'

Sample response

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

Note: Make a note of the accessToken in the response. This is the system to system token referred to as the client-authorization-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.

6. 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
}

View OR Update Customer's Profile in SSO Widget

You can view or update customer's profile in SSO Widget after Step 3 (Get User Authorization Token using Access Code) by following the below mentioned Step a and Step b.

For an illustrated overview of the steps involved here, see the sequence diagram below:

a. Get Access Code Using User Authorization Token

You can use the Access Code that you get from /api/v2/auth/accessCode endpoint to view or update customer's profile in SSO widget. Use the accessToken (obtained in Step 3) above as Bearer in the Authorization header.

Key Request Parameters

Sample Request

curl --location --request POST 'https://test.id.customer.shell.com/api/v2/auth/accessCode' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **************' \
--header 'x-sso-market: en-TH'

Sample Response

{
    "accessCode": "**************",
    "expiresIn": 30
}

b. Access OR Update Customer Profile

You can use the obtained accessCode in Step a above to access or edit profile of a customer. You need to pass the accessCode as a query parameter in the SSO Widget as seen below:

https://test.login.consumer.shell.com/profile?page=editprofile&redirect=<redirect-url>&market=<country-code>&clientId=<client-id>&accessCode=<access-code>

Note: The generated accessCode is valid only for 30 seconds. Hence, view profile / edit profile URL should use this accessCode within 30 seconds of the generated time.

Troubleshooting Authentication

Errors returned from Shell's API Management Gateway

Common authentication errors and possible causes