Documentation

Scopes

Elevate, May 20-22-2025, Miami Beach, Florida

Granting the minimum scopes necessary helps to safeguard your Project and its data.

  • After completing this page, you should be able to:

    • Use an API Client for different authorization flows and scenarios (client credentials, password, and anonymous).

    • All OAuth 2.0 clients and access tokens have a scope. The scope constrains the endpoints and resources to which a client has access. This includes whether a client has read or write access to an endpoint. Scopes are immutable and defined for a single Project either inside the Merchant Center or with the API Clients endpoint.

    In the API documentation, each resource specifies the required scope(s) to perform an action.

    For example, let's look at Create Review. In the OAuth 2.0 Scopes section, you can see that the manage_products scope is required to create a review.
    Granting the manage_products scope to a token that is exposed to the frontend app would allow the application to create reviews. However, a malicious actor could also use this token to change the product price, create their own products, or make other changes supported by the manage_products scope.
    When you assign a scope, we recommend that you check the Scopes page to understand what a particular scope covers, including the permissions granted to it. This is a good practice to ensure you don't give more permission(s) than is necessary.

    Scope query parameter

    In the grant flow request, you can pass the optional scope query parameter with one or more scopes defined.
    If you do not include the scope query parameter in your request, the token is granted the same scopes as the API Client. In some cases, this could mean excessive permissions are granted.

    Let’s look at an example:

    $curl https://{auth_host}/oauth/{projectKey}/customers/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=password&username=alice@example.com&password=secret&scope=view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"
    In this request, we limit the token scope to view_published_products, manage_my_orders, and manage_my_profile.

    For optimal security and control in commercetools, explicitly define required API scopes during the authentication process. Never rely solely on pre-configured scope limits within your API Client. This practice ensures the token receives the correct permissions, regardless of API Client settings. Although scope validation after authentication is possible, proactively defining them during authentication enhances security. Your application should always verify the presence of necessary scopes and handle any discrepancies as errors. This approach offers consistent protection. Even if you later replace an API Client with one configured for broader access, the scopes granted to the token remain restricted to those initially defined.

    If you use the scope query parameter, it can be tracked in your version control system, giving you additional insight into changes over time. Your version control system might also allow you to configure alerts for changes to specific files, such as those that contain scope definitions. This gives you real-time visibility when a potentially sensitive change occurs.
    Additionally, if you specify a scope in the scope query parameter that is not available on the API Client, the authentication server returns a 400 invalid_scope error. At this point, you can log the error and have your logging system send an alert to notify you of the problem. This approach is more straightforward than manually checking the list of scopes returned from a successful token grant, as capturing and logging errors is preferable to debugging silent errors.

    User types and scenarios

    When creating tokens for users, you need to define the primary user types, the actions these user types will take, and the corresponding scopes. Once defined, you can create a single API Client for all of these user types and grant a token with the appropriate scopes using the scopes query parameter.

    If you choose to use the client credentials flow instead of the password or anonymous flow for your frontend integration, you will need to consider how similar flows map to your session management solution. This also means implementing user-specific access control to restrict access to resources that belong to users, such as Carts, Orders, and Shopping Lists.

    The following user types contain scope suggestions. Each Composable Commerce implementation is unique and may need slightly different scopes. When creating tokens on behalf of users, always grant the least amount of scopes necessary.

    Stateless crawler or guest user

    This user type could be a search engine bot or a non-authenticated user that is only browsing the website. In this case, you can create an anonymous token that has read-only scopes.

    Suggested scopes for this scenario:

    • view_categories
    • view_published_products or view_products
    • view_standalone_prices (if your project is using Standalone Prices)
    • create_anonymous_token

    In this scenario, you should create a read-only token that can be shared between users (including stateless web crawlers), to limit the amount of active tokens. By creating a read-only token, you ensure that the user can't create resources. Additionally, sharing the token will not leak user-specific resources such as Carts, Shopping Lists, or Orders.

    You should create anonymous sessions only once necessary, for example, when the visitor creates a Cart, Shopping List, or other user-specific resource.

    In scenarios where visitors create resources, you must use separate tokens for each user. To convert the user to a different user type, use a new flow to grant the appropriate token to the user.

    Stateful crawler or guest user creating resources

    This type of user has transitioned from browsing to actively performing user-specific actions, such as adding items to a Cart or creating an Order.

    Keep in mind that even stateful crawlers will attempt some of these behaviors. For example, a stateful crawler may check the price of a product on a product detail page, then add the product to a Cart. This allows the bot to check for price discrepancies that may exist in line items, taxes, and shipping costs.

    In this case, you can still use an anonymous token flow, but with a token that is unique to the user and with more scopes.

    Suggested scopes for this scenario:

    • view_categories
    • view_published_products or view_products
    • view_shipping_methods
    • view_standalone_prices
    • manage_my_orders
    • manage_my_payments
    • manage_my_shopping_lists
    • create_anonymous_token

    Logged-in users

    This type of user has de-anonymized their session by logging in to an existing account, or by creating a new account.

    In this case, you can use similar scopes to the stateful crawler user type, with the exception of create_anonymous_token.

    Suggested scopes for this scenario:

    • view_categories
    • view_published_products or view_products
    • view_shipping_methods
    • view_standalone_prices
    • manage_my_business_units
    • manage_my_orders
    • manage_my_payments
    • manage_my_profile
    • manage_my_quote_requests
    • manage_my_quotes
    • manage_my_shopping_lists

    We can now add all of these scopes together into a single de-duplicated list and create the API Client.

    Test your knowledge