Authentication and Authorization

All Custom API endpoints must be secured by authentication (AuthN) and authorization (AuthZ).

To secure your endpoints, complete the following steps:

  1. Decide whether the endpoint is used by a shopper or an admin.
  2. Define a custom scope for the endpoint.
  3. Update your API client to include the new custom scope in authentication tokens.

You can select either ShopperLogin or AmOAuth2 as the security scheme to protect your endpoints. For shopper APIs and storefront use cases, use Shopper Login (SLAS). For admin or merchant APIs to be used with backoffice apps, use Account Manager Auth (AmOAuth2). These security schemes are exactly the same ones that are used for SCAPI platform APIs.

This guide explains the necessary configuration in these components:

  • The API contract (i.e. the OAS schema file)
  • The service that issues the authentication tokens (i.e. SLAS or CC Account Manager)

To secure API access, add the scheme(s) to the components section of the API contract. The purpose of this section is to define reusable elements. The following code provides a complete definition of both security schemes:

Replace shortCode and organizationId with the values of your instance. Also, add all available custom scopes to the scopes list. For more information on scopes, refer to the Authorization section.

Example: Defining the security schemes with concrete values:

Although the endpoint registration does not check the type and flows fields, adding them is required for the OAS schema to be valid. Also, having a complete and valid schema (including concrete values for the placeholders) enables the generation of documentation, tests and code stubs, and mock requests.

In order to use a security scheme, it must be added to the endpoints. This can be done globally or at each operation. The scheme at an operation has precedence, and will overwrite the global scheme.

Example: Defining the security scheme globally and at an operation:

Endpoints must be associated with a valid security scheme (ShopperToken or AmOAuth2) or they will not be registered. Additionally, each scheme must define exactly one scope wherever it is used. Read the following sections for scope requirement details.

The request to an endpoint is authorized when the comparison of required scopes (i.e. scopes defined in the contract) with granted scopes (i.e. scopes present in the token) results in at least one match (i.e. the intersection of both sets is not empty).

Both security schemes require the definition of required scopes for the request to an endpoint. You must define exactly one scope, otherwise the endpoint will not be registered.

For custom scopes, the following requirements apply:

  • The scope name must begin with the prefix c_.
  • The scope name must not contain characters other than alphanumeric, period, hyphen and underscore.
  • The length of the scope name must not exceed 25 characters.

Defining a scope that doesn't meet these requirements prevents the endpoint from being registered.

Since each endpoint can have only one scope, a scope should refer to the endpoint itself and not to the underlying business objects. If you create an endpoint /readSomething which accesses the business objects A and B, only the scope c_readSomething instead of the two scopes c_readA and c_readB is necessary.

Example 1: Defining the scope c_loyaltyInfo_r for an endpoint secured by ShopperLogin:

Example 2: Defining the scope c_loyaltyInfo_rw for an endpoint secured by AmOAuth2:

Custom scopes for ShopperLogin can be assigned to a client in the SLAS Admin UI. For example:

Associated diagram

Custom scopes for AmOAuth2 can be assigned to a client in Account Manager. For example:

Associated diagram

The steps to obtain a SLAS token are the same for SCAPI platform APIs and Custom APIs. Please refer to the SLAS overview.

However, an AmOAuth2 token requires a few more steps. See Authorization for Admin APIs for details.

First, make sure that your client ID at the Account Manager has the role SALESFORCE_COMMERCE_API assigned with a valid tenant filter for your instance (xxxx_prd in the example request below). For example:

Associated diagram

After that, a token can be obtained from the endpoint https://account.demandware.com/dwsso/oauth2/access_token.

Example: Obtaining an AmOAuth2 for the instance xxxx_prd: