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:

ApplicationClient Type
Single-page web app (for example, a PWA Kit storefront)Public client
Traditional full stack web appPrivate client
Mobile app (Android or iOS)Public client
Any kind of app with a backend-for-frontend (BFF)Private client

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.

SLAS ClientAuthentication MethodMethodGrant TypeToken
PublicNone (guest user)getAccessTokenauthorization_code_pkceShopper
PublicRegistered user (federated login)getAccessTokenauthorization_code_pkceShopper
PublicRegistered user (B2C Commerce login)getAccessTokenauthorization_code_pkceShopper
PrivateNone (guest user)getAccessTokenclient_credentialsShopper
PrivateRegistered user (federated login)getAccessTokenauthorization_codeShopper
PrivateRegistered user (B2C Commerce login)getAccessTokenauthorization_codeShopper
PrivateRegistered user (B2C Commerce login)getAccessTokenauthorization_code_pkceShopper
PrivateTrusted system on behalf of (TSOB) usergetTrustedSystemAccessTokenclient_credentialsShopperTsob
PublicSession Bridge (guest user)getSessionBridgeAccessTokensession_bridgeShopperSesb
PublicSession Bridge (B2C Commerce login)getSessionBridgeAccessTokensession_bridgeShopperSesb
PrivateSession Bridge (guest user)getSessionBridgeAccessTokenclient_credentialsShopperSesb
PrivateSession Bridge (B2C Commerce login)getSessionBridgeAccessTokenclient_credentialsShopperSesb
PrivateTrusted agent on behalf of (TAOB)getTrustedAgentAccessTokenclient_credentialsShopperTaob

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.

As of 7/31/2024, for existing SLAS customers, SLAS requires a channel_id (site) parameter when requesting a guest access token with a grant_type of client_credentials or authorization_code_pkce. Requiring a channel_id prevents cross site access from one channel_id to another. A related change prevents usage of SLAS shopper tokens created for one site (Site A) to be used for making SCAPI and/or OCAPI calls for another site (Site B). This prevents cross-site shopper token usage.

To allow SLAS customers more time to make the necessary changes for passing the channel_id for guest access token requests, the following tiered approach is in place:

  • Starting 09/01/2024, all Sandbox tenant_ids will receive a Bad Request (400) response if a channel_id parameter is not provided in the guest token request.
  • Starting 10/01/2024, all Staging (STG) and Development (DEV) tenants_ids will receive a Bad Request (400) response if a channel_id parameter is not provided in the guest token request.
  • Starting 10/15/2024, all Production (PRD) tenants_ids will receive a Bad Request (400) response if a channel_id parameter is not provided in the guest token request.

For example:

The SLAS access_token that was requested for channel_id RefArch can only be used with SCAPI / OCAPI calls using the the same site_id:

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>'`

We will work with tenants and send out a TRUST notification announcing this change. We are also adding an allowlist with current Production tenants to allow time to make the necessary changes. The allowlist will be in effect after the SLAS June deployment. If exceptions are needed, contact your Customer Success Manager or Account Executive.

What You Must Do For This Change

Always provide the channel_id parameter when fetching tokens:

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"

If you are getting a SLAS guest token using the grant_type of client_credentials without providing the channel_id parameter, you must update the SLAS guest token call and add the channel_id parameter. If the channel_id parameter is missing, a HTTP Bad Request (400) response is thrown. For example:

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'

Request with a channel_id parameter:

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'

If you are getting a SLAS guest token using the grant_type of authorization_code_pkce without providing the channel_id parameter, you must update the SLAS guest token call and add the channel_id parameter. If the channel_id parameter is missing, a HTTP Bad Request (400) response is thrown. For example:

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'

Request with a channel_id parameter:

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:
  1. 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:
  1. 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.

With B2C Commerce version 24.10, the SLAS 4xx 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 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:

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.

  • 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.
    • 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:

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