Learning PathModule

Scopes

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

Ask about this Page
Copy for LLM
View as Markdown

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. Scope constraints include 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. The following request obtains a password flow token with specific scopes. For the complete token request format and all parameters, see Password flow for global Customers.
$curl https://{auth_host}/oauth/{projectKey}/customers/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=password&username={email}&password={password}&scope=view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"
In this request, the scope parameter limits the token scope to view_published_products, manage_my_orders, and manage_my_profile. The full password flow example request is in the HTTP API authorization reference.

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. Defining scopes during authentication ensures the token receives the correct permissions, regardless of API Client settings. Although scope validation after authentication is possible, proactively defining scopes during authentication enhances security. Your application should always verify the presence of necessary scopes and handle any discrepancies as errors. Proactive scope definition offers consistent protection. Even if you later replace an API Client with broader access, the token's scopes remain restricted to those initially defined.

If you use the scope query parameter, scope definitions can be tracked in your version control system. Your version control system might also allow you to configure alerts for changes to files that contain scope definitions. Version-controlled scope definitions give you real-time visibility when a potentially sensitive change occurs.
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. You can log the error and have your logging system send an alert. Capturing scope errors is more straightforward than manually checking the scopes returned from a successful token grant.

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 user types. Grant a token with the appropriate scopes using the scope query parameter. For the complete list of available scopes and their descriptions, see Scopes.

If you use the client credentials flow for your frontend integration, consider how it maps to your session management solution. The client credentials flow also requires implementing user-specific access control to restrict access to resources like 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