OCAPI JWT 15.6

JSON Web Token (JWT) is an authentication mechanism required by several Shop API resources. You do not have to be completely familiar with JWT to use these resources; however, for more information about JWT, see the JSON Web Token (JWT) IETF specification.

Your client application is responsible for keeping customer credentials and authentication (JWT) tokens secure. Your application must use these tokens to interact with the Shop API on behalf of the purchasing customer (registered or guest).

Your client application can obtain a JWT token for a customer by using the /customers/auth resource.

Preparation

Before you can use JWT for authentication, you must register your client application using Account Manager. See Adding a client ID for the Open Commerce API.

Account Manager provides you with a client ID that is known to both Salesforce B2C Commerce and your client application. The client ID is required when you request an authentication token. On sandboxes, for testing, you can use the demo client ID: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.

In addition to obtaining the authentication token, you must configure client permissions to grant your client application access to the Open Commerce APIs.

Authentication steps

To use JWT tokens for authentication, your client application must perform the following steps:

  1. Request an authentication token (JWT) using the /customers/auth resource.

  2. Include the authentication token in subsequent Shop API requests.

  3. Refresh the authentication token if needed.

When you request an authentication token using the /customers/auth resource, you must specify your client ID as a URL or header parameter. You must also specify the type of customer:
  1. Specify "type":"guest" to request a guest customer authentication token.
  2. Specify "type":"credentials" to request a registered customer authentication token. (For a registered customer, you must also include the customer login and password in the HTTP Basic Authentication scheme.)
If the request succeeds, the response includes an authentication token in the Authentication:Bearer response header. The response also includes a description of the customer in the response body. Your application must include the authentication token in the Authentication:Bearer header of subsequent requests.

The authentication token is a signed JWT. This means that the JWT token's header and payload sections are JSON-formatted strings. Your client application can therefore easily read the various claims in the payload section, such as exp (the token expiration-time) and iat (the token issued-at-time).

An authentication token 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 resource to obtain a new token in exchange for an existing one. You must include the current token in the Authentication:Bearer request header, and you must specify the customer type as "type":"refresh".

The /customers/auth request is based on an HTTP POST operation, which uses transport layer security; 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.

JSON Web Token details

The JWT specification stipulates that a JWT token contains three sections in the following order:

The system returns the JWT token as a Base64-encoded string. In this string, the header, payload, and signature sections are delimited by periods(.).

B2C Commerce uses a subset of the claims defined in the JWT IETF specification. You can decode the payload section to access the values of the exp, iat, sub, and iss claims. For example:
{
      "exp": 1300819380,                      // token expiration-time as seconds from 1970-01-01T00:00:00Z
      "iat": 1300819000,                      // token issued-at-time as seconds from 1970-01-01T00:00:00Z
      "sub": ... ,                            // token subject (see below)
      "iss": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" // token issuer - the client ID 
}
The value of the sub claim is a JSON string. For example:
{
      "customer_id":"12a4567f9123",           // customer id
      "guest":false                           // whether customer is guest (true) or registered (false)
}

JWT examples

The following examples show sample requests and responses using JWT for authentication (additional examples are provided within the resource documentation):

# Obtain a token for a registered customer.
# Credentials are username:password (Base64-encoded) passed via HTTP Basic Auth.

REQUEST:
POST /dw/shop/v15_6/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
  "type" : "credentials"
}


# If the server finds a customer with the given credentials, it returns a 
# newly created token (a JWT) in the Authorization:Bearer response header. 
# The value of the auth_type property is "registered" because the type 
# property was set to "credentials" in the request.

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "15.6",
   "_type" : "customer",
   "auth_type" : "registered",
   "customer_id" : "abdtkZzH6sqInJGIHNR1yUw90A",
   "preferred_locale" : "default"
   ...
}


# All subsequent requests include the token in the Authorization:Bearer header. 
# For example, the following request asks the server to create a new basket for
# the registered customer. The client ID is not required.

REQUEST:
POST /dw/shop/v15_6/baskets
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Host: example.com
Content-Type: application/json


# The server returns information for the newly created basket.

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "15.6",
   "_type" : "basket",
   "basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
   "currency" : "USD",
   ....
}   
OCAPI obsolete versions 13.x and 14.x will be end of life in 2020 and versions 15.x and 16.x in 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.