Scopes
All OAuth 2.0 clients and access tokens have a scope that restricts the clients' access to the endpoints. Depending on the scope granted, a client can have read or write access to an endpoint.
You can define scopes when creating an API Client using the Merchant Center or through the API Clients API. When creating a client or requesting an access token, only provide scopes required by your application. If you do not provide a scope, the access token is granted to all the scopes defined for the API Client. When requesting an OAuth 2.0 access token, the scope parameter can be omitted.
For information about scopes related to other commercetools products, see Import API, Connect, Checkout, or Frontend.
External OAuth
external_user_id:{externalUserId}: set by an external OAuth server to indicate the user that created or modified a resource. When set, theexternalUserIdfield is added to the resource's CreatedBy BETA or LastModifiedBy BETA.
Composable Commerce OAuth
customer_id:{id}: set by the authorization service when using the password flow. When used in combination with a Me endpoint scope, grants access to a Customer with the givenid.anonymous_id:{id}: set by the authorization service when requesting an access token for an anonymous session. When used in combination with a Me endpoint scope, grants access to the anonymous session with the givenid.create_anonymous_token:{projectKey}: grants access to obtain an access token for an anonymous session.introspect_oauth_tokens:{projectKey}: grants access to introspect tokens issued to other clients.
Project configuration
Project
manage_project:{projectKey}: grants permission to use all Composable Commerce APIs in a Project, except API Clients.Do not use in production; instead, create an API Client and only specify the scopes that your application requires. An API Client using this scope cannot request a token with lesser scopes.
In addition, grants permission to use all Connect and Import API endpoints. To access individual endpoints, use more selective permissions for Connect and Import API.
API Clients
view_api_clients:{projectKey}: grants permission to view API Clients in a Project.manage_api_clients:{projectKey}: grants permission to view, create, and delete API Clients in a Project.
Project settings
view_project_settings:{projectKey}: grants permission to view Project settings.manage_project_settings:{projectKey}: grants permission to view and update Project settings in a Project.
Stores
Tax Categories
view_tax_categories:{projectKey}: grants permission to view Tax Categories in a Project.manage_tax_categories:{projectKey}: grants permission to view, create, update, and delete Tax Categories in a Project.
Product catalog
Products
To ensure backward compatibility, these scopes also grant permissions to access Categories, Tax Categories, and Custom Objects.
view_products:{projectKey}: grants permission to view Product Types, Products, Channels, InventoryEntries, Reviews, ProductDiscounts in a Project.manage_products:{projectKey}: grants permission to view, create, update, and delete Product Types, Products, Channels, Inventory Entries, Reviews, Product Discounts in a Project. It also implies the scope to view published Product Projections.In addition, it also grants permission to the following: Import Categories, Import Product Types, Import Products, Import Product Drafts, Import Product Variants, Import Product Variant Patches, Import Inventories, and Import Embedded Prices.
Product Projections
view_published_products:{projectKey}: grants permission to view published Product Projections in a Project.When using the GraphQL API, grants permission to query for
masterData.currentonproductsinterface and publishedproductProjectionSearchresults.
Attribute Groups
view_attribute_groups:{projectKey}: grants permission to view Attribute Groups in a Project.manage_attribute_groups:{projectKey}: grants permission to create, update, and delete Attribute Groups in a Project.
Product Selections
view_product_selections:{projectKey}: grants permission to view Product Selections in a Project.manage_product_selections:{projectKey}: grants permission to view, create, update, and delete Product Selections in a Project.
Categories
view_categories:{projectKey}: grants permission to view Categories in a Project.manage_categories:{projectKey}: grants permission to view, create, update, and delete Categories in a Project.
Pricing and Discounts
Standalone Prices
view_standalone_prices:{projectKey}: grants permission to view Standalone Prices in a Project.manage_standalone_prices:{projectKey}: grants permission to view, create, update, and delete Standalone Prices in a Project.In addition, it also grants permission to Import Standalone Prices.
Cart Discounts
view_cart_discounts:{projectKey}: grants permission to view Cart Discounts in a Project.manage_cart_discounts:{projectKey}: grants permission to view, create, update, and delete Cart Discounts in a Project.view_cart_discounts:{projectKey}:{storeKey}: grants permission to view Cart Discounts in a specific Store in a Project.manage_cart_discounts:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Cart Discounts in a specific Store in a Project.
Discount Codes
view_discount_codes:{projectKey}: grants permission to view Discount Codes in a Project.manage_discount_codes:{projectKey}: grants permission to view, create, update, and delete Discount Codes in a Project.
Customers
Customers
To ensure backward compatibility, these scopes also grant permissions to access Customer Groups and Custom Objects.
view_customers:{projectKey}: grants permission to view Customers in a Project.manage_customers:{projectKey}: grants permission to view, create, update, and delete Customers in a Project.In addition, it grants permission to Import Customers.
view_customers:{projectKey}:{storeKey}: grants permission to view Customers in a specific Store in a Project.manage_customers:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Customers in a specific Store in a Project.
Customer Groups
view_customer_groups:{projectKey}: grants permission to view Customer Groups in a Project.manage_customer_groups:{projectKey}: grants permission to view, create, update, and delete Customer Groups in a Project.
Me endpoints
My Customer Profile BETA
manage_my_profile:{projectKey}: grants permission to view, create, update, and delete the profile for a Customer using an access token from the password flow.When used to generate an access token for an anonymous session or client credentials flow, grants access to sign up and sign in a Customer.
manage_my_profile:{projectKey}:{storeKey}: When used in the password flow, grants permission to view, create, update, and delete the profile for a Customer from a Store in a Project.When used to generate an access token for an anonymous session, grants access to sign up and sign in a Customer in a Store.
For more information about resources projected to a Store, see Helpers in the HTTP and GraphQL APIs.
My Business Units BETA
manage_my_business_units:{projectKey}: grants permission to view, create, and update Business Units for a Customer using an access token from the password flow.
My Orders BETA
manage_my_orders:{projectKey}: grants permission to view, create, update, and delete Carts, and view and create Orders for a Customer using an access token from the password flow.When used to generate an access token for an anonymous session, grants access to the Orders of an
anonymousId.manage_my_orders:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Carts, and view and create Orders for a Customer in a specific Store using an access token from the password flow.When used to generate an access token for an anonymous session, grants access to the Orders of an
anonymousId.
For more information about resources projected to a Store, see Helpers in the HTTP and GraphQL APIs.
My Payments BETA
manage_my_payments:{projectKey}: grants permission to view, create, update, and delete Payments for a Customer using an access token from the password flow.When used to generate an access token for an anonymous session, grants access to the Payments of an
anonymousId.
My Shopping Lists BETA
manage_my_shopping_lists:{projectKey}: grants permission to view, create, update, and delete Shopping Lists for a Customer using an access token from the password flow.When used as a scope to generate an access token for an anonymous session, grants access to the Shopping Lists of an
anonymousId.manage_my_shopping_lists:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Shopping Lists of a Customer in a specific Store using an access token from the password flow.When used as a scope to generate an access token for an anonymous session, grants access to the Shopping Lists of an
anonymousId.
For more information about resources projected to a Store, see Helpers in the HTTP and GraphQL APIs.
My Quote Requests BETA
manage_my_quote_requests:{projectKey}: grants permission to view, create, and update Quote Requests for a Customer using an access token from the password flow.
My Quotes BETA
manage_my_quotes:{projectKey}: grants permission to view and update Quotes for a Customer using an access token from the password flow.
Business Units
Business Units
view_business_units:{projectKey}: grants permission to view Business Units and Associate Business Units in a Project.manage_business_units:{projectKey}: grants permission to view, create, update, and delete Business Units and Associate Business Units in a Project.
Associate Roles
view_associate_roles:{projectKey}: grants permission to view Associate Roles in a Project.manage_associate_roles:{projectKey}: grants permission to view, create, update, and delete Associate Roles in a Project.
Approval Rules
view_approval_rules:{projectKey}: grants permission to view Approval Rules in a Project.manage_approval_rules:{projectKey}: grants permission to view, create, update, and delete Approval Rules in a Project.
Approval Flows
view_approval_flows:{projectKey}: grants permission to view Approval Flows in a Project.manage_approval_flows:{projectKey}: grants permission to view, create, update, and delete Approval Flows in a Project.
Cart and Order management
Carts
See Orders.
Orders
To ensure backward compatibility, these scopes also grant permissions to access Cart Discounts, Discount Codes, States, Shipping Methods, and Custom Objects.
view_orders:{projectKey}: grants permission to view Carts, Orders, Associate Carts, Associate Orders, Zones in a Project.manage_orders:{projectKey}: grants permission to view, create, update, and delete Carts, Orders, Associate Carts, Associate Orders, Zones in a Project.In addition, it grants permission to Import Orders and Import Order Patches.
view_orders:{projectKey}:{storeKey}: grants permission to view Carts and Orders in a specific Store in a Project.manage_orders:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Carts and Orders in a specific Store in a Project.
For more information about resources projected to a Store, see Helpers in the HTTP and GraphQL APIs.
Payments
Shopping Lists
view_shopping_lists:{projectKey}: grants permission to view Shopping Lists in a Project.manage_shopping_lists:{projectKey}: grants permission to view, create, update, and delete Shopping Lists in a Project.view_shopping_lists:{projectKey}:{storeKey}: grants permission to view Shopping Lists in a specific Store in a Project.manage_shopping_lists:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Shopping Lists in a specific Store in a Project.
For more information about resources projected to a Store, see Store Helpers in the HTTP API and GraphQL API.
Order Edits
view_order_edits:{projectKey}: grants permission to view Order Edits in a Project.manage_order_edits:{projectKey}: grants permission to view, create, update, and delete Order Edits in a Project.
Shipping Methods
view_shipping_methods:{projectKey}: grants permission to view Shipping Methods in a Project.manage_shipping_methods:{projectKey}: grants permission to view, create, update, and delete Shipping Methods in a Project.
Quote Requests
view_quote_requests:{projectKey}: grants permission to view Quote Requests in a Project.manage_quote_requests:{projectKey}: grants permission to view, create, update, and delete Quote Requests and Associate Quote Requests in a Project.view_quote_requests:{projectKey}:{storeKey}: grants permission to view Quote Requests in a specific Store in a Project.manage_quote_requests:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Quote Requests in a specific Store in a Project.
For more information about resources projected to a Store, see Store Helpers in the HTTP API and GraphQL API.
Staged Quotes
view_staged_quotes:{projectKey}: grants permission to view Staged Quotes in a Project.manage_staged_quotes:{projectKey}: grants permission to view, create, update, and delete Staged Quotes in a Project.view_staged_quotes:{projectKey}:{storeKey}: grants permission to view Staged Quotes in a specific Store in a Project.manage_staged_quotes:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Staged Quotes in a specific Store in a Project.
For more information about resources projected to a Store, see Store Helpers in the HTTP API and GraphQL API.
Quotes
view_quotes:{projectKey}: grants permission to view Quotes and Associate Quotes in a Project.manage_quotes:{projectKey}: grants permission to view, create, update, and delete Quotes and Associate Quotes in a Project.view_quotes:{projectKey}:{storeKey}: grants permission to view Quotes in a specific Store in a Project.manage_quotes:{projectKey}:{storeKey}: grants permission to view, create, update, and delete Quotes in a specific Store in a Project.
For more information about resources projected to a Store, see Store Helpers in the HTTP API and GraphQL API
API extensibility
Types
view_types:{projectKey}: grants permission to view Types in a Project.manage_types:{projectKey}: grants permission to view, create, update, and delete Types in a Project.In addition, it also grants permission to Import Types.
Custom Objects
view_key_value_documents:{projectKey}: grants permission to view Custom Objects in a Project.manage_key_value_documents:{projectKey}: grants permission to view, create, update, and delete Custom Objects in a Project.
API Extensions
manage_extensions:{projectKey}: grants permission to view, create, update, and delete API Extensions in a Project.
Subscriptions
manage_subscriptions:{projectKey}: grants permission to view, create, update, and delete Subscriptions in a Project.
Messages
view_messages:{projectKey}: grants permission to view Messages in a Project.
States
Audit Log
Change History
view_audit_log:{projectKey}: grant permission to view Change History.In addition, assign view or manage scopes for the resource type you want to view in Change History. For more information, see Change History scopes.