Authentication and Authorization
All Custom API endpoints must be secured by authentication (AuthN) and authorization (AuthZ).
To secure your endpoints, complete the following steps:
- Decide whether the endpoint is used by a shopper or an admin.
- Define a custom scope for the endpoint.
- 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:
Custom scopes for AmOAuth2
can be assigned to a client in Account Manager. For example:
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:
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
: