Commerce API Authentication

Due to varying security requirements, the Salesforce Commerce API distinguishes authentication methods between shopper-based APIs and all other APIs. Shopper-based APIs have names that begin with “Shopper.” For example, Shopper Products vs. Products.

What’s the difference between the two types of APIs?

  • Shopper APIs target the persona of a storefront shopper. These APIs are accessed as either guest or anonymous users, or as authenticated users against a customer authentication system. Shopper APIs are built for high-scale and usage within a storefront. They are primarily read-only APIs with exceptions being Baskets and Orders.
  • All other APIs are protected and accessed by “high privileged” users that access the Commerce Cloud system via Account Manager. These APIs are often used for merchandisers, advertisers, site operators, support agents, developers, and so on. These APIs are often not as high-scale as Shopper APIs as they are not accessed as often.

Get Your API Client ID

Before doing anything with the Salesforce Commerce API, you need an API Client ID.

The API Client ID is a credential that is granted from Account Manager, that consists of both an ID value and a secret. Both the ID and the secret should be protected and treated as a username and password combination to using the Salesforce Commerce API.

These values are typically provided by your Commerce Cloud System Administrator. If you already have one, great! You can move on to the following API-specific sections. However if you do not have one, refer to the Add an API Client ID documentation in the Commerce Cloud Infocenter.

Shopper APIs

All Shopper API authentication is handled with a JSON Web Token (JWT). To retrieve the shopper JWT, the endpoint /customers/actions must called. The JWT can be requested for guest access and registered customer access.

Prerequisites

  • API Client ID

Guest Token

Registered Customer Token

Either of the preceding calls return an access token:

This access token is then used as a bearer token in subsequent API calls.

Refresh Your Token

A JWT has a lifetime of 30 minutes. Before the token expires, you must exchange it for a new token if you want to extend the total lifetime. You can use the /customers/auth endpoint to obtain a new token in exchange for an existing one. Include the current token in the Authentication:Bearer request header, and you specify the customer type as "type":"refresh". The /customers/auth request is based on an HTTP POST operation, which uses transport layer security, so the request body must be URL encoded. For registered customers, the client ID must be passed in the initial request to obtain the authentication token, but is not needed in subsequent requests.

All Other APIs

Prerequisites

  • API Client ID and secret

Auth Call

Authentication follows the OAuth 2.0 protocol. The access token can be acquired by calling Account Manager:

QWxhZGRpbjpvcGVuIHNlc2FtZQ== is the base-64 encoded clientID

.

This call returns an access token:

This access token is then used as a bearer token in subsequent API calls. For details on bearer token usage in OAuth 2.0, see RFC 6750 from the Internet Engineering Task Force (IETF).