Client Permissions for API Endpoints

In contrast to user permissions, the permission handling considers client permissions only. A client is considered to be a frontend app or any other touchpoint connecting to the Salesforce Commerce API.

The new authentication approach uses OAuth scopes to define permissions. The scopes are provided as part of the JSON Web Token (JWT) claim when requesting an access token for data management or shopping apps.

This new JWT approach with OAuth scopes provides some advantages:

  • Coarse-grained client permissions with read-only and read-write permissions.
  • Define permission once for applicable B2C instances in an instance context.
  • Using Standard technology (OAuth 2.0 access-token scopes).

We use scopes to secure all calls to the Salesforce Commerce API:

  • AM-OAuth2: Used by data management apps, to manage product or customer data.
  • JWT (Shopper JWT): Used by shopping apps to authenticate the client app, and “register“ guest shopper-users and registered shopper-users.

For a list of current scopes, see the AuthZ Scope Catalog.

There are two steps that must be done to utilize the new client permissions by every user of the Salesforce Commerce API:

  1. Create or update an API Client ID that contains the new role, instance assignment, and scopes.
  2. Update your Access token request.

For data management apps, see Request an Access Token for Management APIs.

For shopping apps, see Request an Access Token for Shopping APIs.

Configure the API Client ID

The Salesforce Commerce API requires every API Client ID to be configured with roles, instances, and permissions (in the form of scopes) to define what the client app (the one that authenticates with that API client ID) is allowed to access within the Salesforce Commerce API.

A client ID used for the Salesforce Commerce API cannot be used for calls to the Open Commerce API (OCAPI), and vice versa. Each API framework (Salesforce Commerce API and OCAPI) requires its own client ID. An API client ID that is meant for OCAPI must not have the role “salesforce commerce API” assigned to it.

A properly configured client ID can be used for every organization that it is defined for. There is no need to define API endpoint permissions on every instance any longer.

The scope pattern is {{cloud}}.{{value}}[.rw].

Samples:

  • sfcc.shopper-products
  • sfcc.shopper-myaccount.addresses.rw
  • sfcc.products
  • sfcc.products.rw

Since a scope represents a use-case-specific permission, it may cover multiple endpoints where it seems reasonable.

  1. Create a Client ID in Account Manager.

    For more information, see Add an API Client ID in the Salesforce B2C Commerce Infocenter.

  2. Assign the new Commerce API role to the API Client ID.

    1. In Roles, click Add.
    2. Select Salesforce Commerce API, and click Add.
  3. Specify the Commerce API Role Scope.

    1. Click the filter icon.

    2. In the Add Instance Filters tab, select an organization.

    3. Select the instance that you want the API Client ID to be used for, and click Add.

      Note: When you use the client ID to request an access token, you must specify the specific instance you want the access token for. This instance must be specified, otherwise an access token is not provided.

  4. Assign scopes to the Client ID.

    In the Allowed Scopes field, enter all scopes that you need for the client ID to work for your respective use cases.

    Client Permissions for API Endpoints

Be sure that the scopes are entered correctly into the field, otherwise access to endpoint is not provided. Note: A scope that ends with .rw always includes the read-only rights of a scope that does not end with .rw.

  1. Select client_secret_post as the Endpoint Auth method.

    This method must be selected since requesting an access token is done by authenticating the client with a client ID and its related secret.

  2. Select JWT as the Access Token Format, as this is the only format we support with the new client AuthZ.

Request an Access Token for Management APIs

Requesting an access token requires three parameters to be provided with Token request:

  • Client ID: the client ID you created that represents the calling application and contains roles, tenant filters, and scopes.
  • Instance assignment via tenant ID: represents the ecommerce environment you request the access token for. You can define multiple instances with a client ID, but you can only request an access token with one instance ID (out of the set that is defined for the client ID).
    Note: the tenant ID is part of your organization ID f_ecom_{{tenant_id}}. Example: for organization ID f_ecom_zzzz_001, the tenant ID is zzzz_001.
  • Scopes: you must add the scopes in the request that you want the access token works with specifically. They will be checked against the allowed scopes for the client ID, which is a master list of all scopes that a client can access.

The generated JWT access-token contains the list of scopes added to the access token request. If no scopes are provided in the access token request, the JWT (access-token) is generated with default scopes defined for the clientID. We do not recommend defining all scopes as default scopes for the clientID.

The {{client_id}}:{{client_secret}} must be base64 encoded.

Request an Access Token for Shopping APIs

Request an access token for a guest user, with the client ID.

There is no need to specify instance and scopes in the token request.

  • The instance information is implicitly derived from the OrgID in the path.
  • Scopes are always provided back to what is listed at the API client ID.

Scope Transfer with API Requests

Both kinds of JWTs (OAuth access-token and JWT for Shopper APIs) are transferred with each API request via Authorization Header Bearer Scheme: