Shell Authentication Quickstart

Introduction

The Shell Authentication API enables partner applications to authenticate with the API Gateway using OAuth 2.0 client credentials flow. This API provides time-sensitive access tokens that authorize requests to Shell APIs, ensuring secure communication between your application and Shell's services.

Authentication

Migration Note

This API provides both v1 and v2 versions of the OAuth token endpoint. Version 1 is deprecated and will be removed in an upcoming change window. New integrations should use v2, and existing users should migrate to v2 as soon as possible. The primary differences are in the response format: v2 uses standard OAuth field names (expires_in instead of expires_in(seconds) and Bearer instead of BearerToken).

Authorization flow

1. Request Client ID and Secret

Contact Shell API Team in order to request access to OAuth authentication. The Shell API team will provide a Client ID and Secret.

2. Request Bearer token

Once you get the credentials, make a request to the Shell Authentication API's OAuth token endpoint with your credentials.

Example 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'

You'll receive a Bearer token in the response:

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

Note: The bearer token expiration time is provided in seconds.

3. Authorize API requests

When calling Shell APIs, include the following in the header of the request.

Authorization: Bearer access_token

Base URLs

Core Integration

1. Generate OAuth Token

Description: Request an OAuth access token using your client credentials. The API returns a time-sensitive Bearer token that must be included in the Authorization header of all subsequent API requests. For security measures, the POST method is used instead of GET to prevent caching.

Path: POST /v2/oauth/token

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=twuwywTYUHAH6AHHJ' \
--data-urlencode 'client_secret=yuahaYThdvdowoUUU7wjsjMM' \
--data-urlencode 'grant_type=client_credentials'

Request Parameters

Sample Response

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

Response Parameters

Error Handling

The API uses standard HTTP status codes. In case of an error, additional details will be provided in the response body.