Getting Started with ExxonMobil APIs

APIs have become key components of business innovation and collaboration across many industries. The ExxonMobil Developer Hub provides a convenient, easy-to-use resource for sharing our APIs with our customers, suppliers, and third-party service providers. 

Getting started on the ExxonMobil Developer Hub is quick, easy, and free. This guide provides all the information you need.

To access our API specifications and documentation, you’ll need to create an account on our Hub. Just follow these steps: 

1. Click on Sign up, located in the top right corner of the page.  

2. Enter the required information.  

3. Review and accept EM API Terms of Use.

4. Click the Sign Up button.

5. You will receive an email with a link to activate your new account. Click on this and set up your password. Once your account is activated, you may follow instructions in Log In section below to access the API Developer Hub.

To access the API Developer Hub:

1. Open your internet browser, navigate to https://developer.exxonmobil.com, and click the "Login" link. 

2. You will be directed to https://apihub.exxonmobil.com. Use the button on the page “External User Login”.

3. Enter the email address and password that you provided when following instructions above to create your API Developer Hub account.

 

APIs relevant to your account will be visible on the Hub upon login.

If you don't find the specific API you're looking for, please use search field at the top of the screen. 

You may filter your search by: 

• Category – search APIs based on a common characteristic. 

• Collections – search APIs by persona, for example, Customers / Distributors, Service Providers, Raw Material Suppliers, etc. 

• Tags – search APIs based on custom attributes, for example, chemical (APIs developed for chemical customers, 3PSPs, suppliers etc. of ExxonMobil), warehouse (APIs developed for warehouse service providers), etc.

Once you receive your search results, select an API to visit the documentation page and learn more. 

Every API has a documentation page where you will find most of the information you need to get started, including: 

• Navigation.

• A list of endpoints.

• Documentation for the currently selected endpoint.

• Code snippets (available in many different programming languages).

• Example responses and error codes.

To connect & test the APIs in a non-production testing environment, please follow the steps below to request for credential setup & API token.

Step 1: Request for an account to call APIs

Submit a request via ‘Support’ form, located in the top right corner of the page, with following info:

• Company Name:
• Business Contact Name / Email:
• IT Contact Name / Email:

Once the account is created, you will be provided the following credentials:

• client_id and client_secret for calling the APIs

Please keep these credentials secured! Do not hard-code them in source code, or store them in the plain text.

Step 2: Get a token

ExxonMobil APIs use OAuth2 Client Credentials Grant Flow to authenticate requests. An access token is required before calling APIs successfully.

To get a token, make a POST call to https://easd.exxonmobil.cloud/oauth2/aus7c0g2jtagArktv1d7/v1/token

Okta requires two header fields to be set on the request: “Authorization”, and “content-Type”.

Because Okta uses Basic Authentication, to pass your client_id and client_secret, you will need to set the “Authorization” header to a Base-64 encoded client_id + client_secret, separated by a colon, as shown below.

Your client_id and client_secret for production environment will be different from the test environment. To get a token for production, change the request URL to https://eas.exxonmobil.cloud/oauth2/aus8jbxzym7yn5FKC697/v1/token.

The “content-Type” header will be “application/x-www-form-urlencoded”, with the following key-value encoded to the url.

grant_type=client_credentials

The two additional headers will look like the following:

POST /oauth2/aus7c0g2jtagArktv1d7/v1/token HTTP/1.1
content-Type: application/x-www-form-urlencoded
Authorization: Basic <your encoded client_id and client_secret>

You can find access_token in the HTTP response if the call is successfully made. A token will expire after 8 hours by default. When the token expires, repeat the request to token endpoint to acquire a fresh new access token.

{

      “access_token”: “your_access_token”,

      “expire_in”: 28800,

      “token_type”: “Bearer”

}

Step 3: Use a token

Now that you’ve acquired a token, use the token to make requests to the resource by passing through Authorization header using Bearer scheme.

The base URL is: https://uat.api.ext.exxonmobil.com and all API requests must be made over HTTPS with TLS 1.2.

GET /customer/chem/v1/accounts HTTP/1.1

Host: uat.api.ext.exxonmobil.com

Authorization: Bearer {your_access_token}

Content-Type: application/json

{

      “data”: {...}

}

Status codes

The following status codes are returned by the API.

Status Code	Description
200 OK / 201 Created	Request successful
400 Bad Request	Problem with the request
401 Unauthorized	Valid access token is not specified
403 Forbidden	Not authorized to access the resource
404 Not Found	The requested resource does not exist
500 Internal Server Error	Error on the internal server