Shopper Login and API Access Service(SLAS) Overview

The Shopper Login and API Access Service (SLAS) enables secure access to the Shopper APIs of the B2C Commerce API and the Open Commerce API (OCAPI).

We offer two admin tools for setting up SLAS: the SLAS Admin API and the SLAS Admin UI. Both admin tools use Account Manager for access control, and they both require that you have the SLAS Organization Administrator role and the correct filters applied for your B2C Commerce instances.

To access the SLAS Admin UI, replace {{short-code}} in the following URL with the short code used by your B2C Commerce instances:

To learn more about short codes, see the Base URL and Request Formation guide.

For advice on how to use SLAS under high-volume situations, see this article on the Salesforce Developers blog: Shopper Login API: Techniques and Tricks to Get the Most Out of High-Volume Holidays.

To make authorized requests to SLAS, each application must be associated with one or more SLAS clients. Each SLAS client is registered to a single SLAS tenant and each SLAS tenant is associated with a single B2C Commerce instance.

A SLAS client can be created as one of two types: public or private. To choose the right client type for your application, the most important thing to ask is whether the client can be trusted to securely store a client secret or not. Use a private client when you can trust the client and use a public client when you cannot.

For example, a mobile app that communicates directly with SLAS must store the client secret on the shopper’s device, which is not secure. Therefore, most mobile apps use a public client. On the other hand, a mobile app with a backend for frontend (BFF) system can store a client secret in a secure location where the shopper’s device cannot access it. Any app with a BFF system can use a private client.

The following table summarizes which client types are used by the most common types of applications:

The SLAS API is based on grant types defined by the OAuth 2.1 standard.

The grant type used for an access token request depends on the type of SLAS client (public or private) and the shopper’s authentication method.

Most SLAS clients request access tokens with the getAccessToken endpoint and receive a ShopperToken.

Trusted systems use the getTrustedSystemAccessToken endpoint and receive a ShopperTsob token. This token has additional capabilities so that trusted systems can make requests on behalf of users.

Agents acting on behalf of shoppers use the getTrustedAgentAccessToken endpoint and receive a ShopperTokenTaob token.

To get a SLAS token for a B2C Commerce session, use the getSessionBridgeAccessToken endpoint.

The following table summarizes the different grant types and token types used by each type of SLAS client and user authentication method.

To request a ShopperToken, use the getAccessToken endpoint. To request a ShopperTokenTsob, use the getTrustedSystemAccessToken endpoint.

Both endpoints return the following upon successful authorization:

• An access token in JSON Web Token (JWT) format
• A customer_id string
• A unique shopper identifier (USID)
• A refresh token

Access tokens are valid for 30 minutes. They can be used to make requests to any B2C Commerce API endpoints covered by the scopes of the issuing SLAS API client. They can request Open Commerce API endpoints for which the SLAS API client ID has been allowed. They may only be used to request APIs from the instance and site they were issued.

The refresh token can be used to request a new access token. For production tenants, refresh tokens are valid for 90 days for registered shoppers and 30 days for guests. On non-production tenants, refresh tokens are valid for 9 days. Using the refresh tokens extends the lifetime of the subsequently issued token by its lifetime duration.

Refresh tokens issued to using public clients are single use. When the refresh token is used, a new one is returned in the response. Refresh tokens issued using private clients may be used multiple times. The same refresh token is returned in the response.

• When a shopper changes their login ID or password, access tokens that were granted before the password change are revoked and rejected by both the B2C Commerce API and OCAPI. Prompt the shopper to log in again using the new credentials. Note that token revocation requires several minutes to complete, and is only enabled by default in production environments. For other environments, such as sandboxes, you must enable token revocation.
• The JWT returned by SLAS includes a number of claims. When writing code to inspect claims, be sure not to rely on ordering, as additional claims may be added.
• Access tokens allow you to act on behalf of the shopper. The actions taken can be sensitive, such as updating an account's email. Always take the necessary precautions to protect the shopper.

curl --location 'https://sandbox-001.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_bcgl_stg/products?ids=nikon-d90-wlens&siteId=RefArch' \
--header 'Authorization: Bearer <access_token>'`

curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/token" \
    --user "$CLIENT:$SECRET" \
    --data 'grant_type=client_credentials' \
    --data "channel_id=$CHANNEL_ID"

curl -X POST --location '[https://<host>/api/v1/organization/<org_id>/oauth2/token](http://localhost:9020/api/v1/organization/bgvn_stg/oauth2/token)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <client_id:secret>' \
--data-urlencode 'grant_type=client_credentials'

curl -X POST --location '`[`https://<host>/api/v1/organization/<org_id>/oauth2/token`](http://localhost:9020/api/v1/organization/bgvn_stg/oauth2/token)`' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <client_id:secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'channel_id=RefArch'

curl --location '[http://<host>/api/v1/organizations/bgvn_stg/oauth2/token](http://localhost:9020/api/v1/organizations/bgvn_stg/oauth2/token)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=4bc7QNx0NDc-n991Ppi6IiwPO6OaPrT_jMgF823lGyg' \
--data-urlencode 'grant_type=authorization_code_pkce' \
--data-urlencode 'redirect_uri=`[`http://localhost:9010/callback`](http://localhost:9010/callback)' \
--data-urlencode 'client_id=3a15f34e-fecd-4fcc-8235-86b70978e629' \
--data-urlencode 'code_verifier=MyLi6hIowxiGsvBvvCJ0FV4AkOpOOnRHxC2PCsvD7yVLy4ZtzKl9Mv9a1r65dh1qg0ZvZ2nvMlLN8uYsZOKcj8cae1XbBBmD'

curl --location '[http://<host>/api/v1/organizations/bgvn_stg/oauth2/token](http://localhost:9020/api/v1/organizations/bgvn_stg/oauth2/token)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=4bc7QNx0NDc-n991Ppi6IiwPO6OaPrT_jMgF823lGyg' \
--data-urlencode 'grant_type=authorization_code_pkce' \
--data-urlencode 'redirect_uri=[http://localhost:9010/callback`](http://localhost:9010/callback)' \
--data-urlencode 'client_id=3a15f34e-fecd-4fcc-8235-86b70978e629' \
--data-urlencode 'code_verifier=MyLi6hIowxiGsvBvvCJ0FV4AkOpOOnRHxC2PCsvD7yVLy4ZtzKl9Mv9a1r65dh1qg0ZvZ2nvMlLN8uYsZOKcj8cae1XbBBmD' \
--data-urlencode 'channel_id=SiteGenesis'

You can view token details in the the decoded access token, such as token lifespan or authorized scopes. For example:

• jku: this is the same as the body iss claim.
• kid : the key id of the public key to use to validate token signature. Get the keys with the getJwksUri endpoint.

• scp: Scopes in the token. Unless specific scopes are requests, this will be the scopes of the SLAS client.
• sub: Contains the client_id, tenant_id, and usid.
• dnt: Shopper tracking preferences. For details, see Manage Shopper Tracking Preferences.
• isb: Contains IDP origin, shopper information, guest id, registered shopper id, token type and channel id.

To help you ensure the authenticity of passwordless login and password reset callbacks, SLAS provides a SlasCallbackToken (JWT) for each passwordless login and password reset callback that SLAS sends:

• SLAS adds a x-slas-callback-token HTTP header with the SlasCallbackToken.
• If SLAS is unable to create the SlasCallbackToken, the x-slas-callback-token HTTP header is not created, and you must use the callback body to retrieve the callback values.

1. Extract the x-slas-callback-token header from the request. Using the previous examples, callback header values are:

2. Use the SLAS /jwks endpoint to get the public key to verify the JWT signature. The response includes public keys for your tenant, for example:

3. Use the public key to verify the SlasCallbackToken signature:

• You can use several Json Web Token (JWT) libraries to verify the SlasCallbackToken signature. See JWT Libraries to find a Json Web Token (JWT) library for your programming language. For example, verify the signature using the Java nimbus-jose-jwt library:

You can incorporate shopper tracking preferences into your applications. When you get a SLAS token using getAccessToken, you specify a tracking preference. The tracking preference is respected for all requests using that token. After the B2C Commerce 24.4. release, the Shopper Login API will include a boolean dnt parameter to set Do Not Track for the session. If not defined, the dnt value defaults to false.

For details, see: Manage Shopper Tracking Preferences.

SLAS 4xx and 5xx error logs are available in Log Center, which provides multiple benefits, including a single URL for all realms, up to 14 days of log data, and improved search capabilities.

To access SLAS 4xx and 5xx error logs:

1. If you built your site using Progressive Web App (PWA) Kit, first complete the prerequisites described in Debug Using Log Center.
2. Start Log Center.
3. Select a Region.
4. Select a Realm. If you don’t know your realm ID, ask your Account Executive (AE) or Customer Success Manager (CSM).
5. Select Show filtered results.
6. Select Search and then select Current Search.
7. In Service Type, select SLAS logs.
8. For a faster search, use an LCQL query, which filters the results using a specific httpStatus code:
   1. Select Search and then select Current Search.
   2. In the Search page, enter an (httpstatus) code for LCQL, for example: text:(httpstatus) AND text:(401).

SLAS supports the following rate limits:

• 24,000 requests per minute (RPM) per tenant for production instances.
• 500 RPM per tenant for non-production instances.
• 25 RPM for the following endpoints: getJwksUri and getWellknownOpenidConfiguration

When a rate limit is reached, SLAS responds with an HTTP 429 Too Many Requests with an HTTP response header Retry-After. The value in the Retry-After header is set to the time in seconds to wait before retrying the request:

Your client code must be able to handle this response. To ensure that the next request is successful, always wait for the specified time before retrying.

To prevent rate limit issues, review the following recommendations:

• Exponential backoff and retry logic: Implement exponential backoff and retry logic, using an API management solution such as Google Apigee.
• Client-side caching: Utilize client-side caching for JWTs, JWKS, and configuration endpoints to reduce the number of API calls. You can manage this effectively using your content delivery network (CDN).
• Unnecessary calls: Optimize your Backend for Frontend (BFF) layer by identifying and eliminating redundant or excessive API requests.
• Token reuse and refresh: Ensure tokens are reused until expiry and avoid frequent token generation.
• Traffic throttling: Implement traffic throttling to limit application calls to 70-80% of the SLAS maximum. This can be managed using the Akamai layer to ensure consistent performance and avoid hitting rate limits.

• A SLAS service protection mechanism restricts calls to the same SLAS endpoint repeatedly using the same USID (Unique Shopper ID) within a short span of time. This returns a 409 HTTP response.

• Some SLAS endpoints, including authenticateCustomer, communicate with the associated B2C Commerce instance. If the instance is unavailable, calls to these endpoints will fail.

• SCAPI hooks including hooks on dw.ocapi.shop.customer.auth.* can conflict with SLAS calls. If SLAS calls are unexpectedly failing, check your B2C Commerce logs for hook invocation errors.

• If a shopper account associated with an access token is disabled or deleted, any subsequent requests made with that access token will fail.

• SLAS is capable of handling a maximum of 30 Custom Object scopes. For details, see Shopper Custom Objects API.

• In B2C Commerce, SLAS functions as a multi-tenant service that serves both PRD and non-PRD instances from its production environment. SLAS treats PRD and non-PRD instances as different "entities", and prioritizes production environment performance by minimizing the potential impact of non-PRD traffic and events to production. As a result, there are SLAS differences between PRD and non-PRD environments, which will be resolved in the future. SLAS PRD and non-PRD differences include:

  • SLAS token revocation behavior after a shopper password or email change: In non-PRD environments, after changing a password or email, it is possible to issue a request using the previously issued SLAS token without receiving an error.
  • When a B2C commerce shopper is deleted, an event is sent to SLAS to delete the corresponding SLAS user. In rare instances, if the delete event does not reach SLAS, you must use deleteShopper to delete the corresponding record in SLAS.
  • Overall eventing (using events to trigger and communicate between services): By default, eventing is only available in PRD instances, so unless this is configured in other environments, it is not available. To have your non-PRD instances evaluated for possible eventing enablement, contact your Customer Success Manager or Account Executive.

If you haven’t already, set up your public SLAS clients or private SLAS clients by following the instructions in Authorization for Shopper APIs in the Get Started guides.

After setting up your SLAS clients, see the SLAS guides that cover how to use both the main SLAS API and the SLAS Admin API:

• Public SLAS Client Use Cases (main SLAS API)
• Private SLAS Client Use Cases (main SLAS API)
• SLAS Identity Providers (SLAS Admin API)

For more technical details on the capabilities of the SLAS APIs, explore the API specifications in the Reference section:

• SLAS API
• SLAS Admin API