Documentation

OAuth scopes and user permissions

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

Learn about applying permissions to your customizations.

OAuth scopes

You can extend the functionality of the Merchant Center by using any of the Composable Commerce APIs. To do this, each customization must specify a list of the required OAuth scopes to satisfy the data fetching requirements.

For example, if you are developing a customization to manage Channels, you would need the OAuth scopes view_products and manage_products. In addition, you might decide to also view Customers information. To fulfill these requirements, your customization would need the following OAuth scopes: view_products, view_customers, and manage_products.
You specify these OAuth scopes in your Custom Application config or Custom View config using the oAuthScopes field:
Custom Application / Custom View configjson
{
  "oAuthScopes": {
    "view": ["view_products", "view_customers"],
    "manage": ["manage_products"]
  }
}
The OAuth scopes are grouped by the view and manage fields, which determine the mapping and relation between OAuth scopes and user permissions.

Permission groups

Every customization has a default permission group with a pair of view and manage permissions. This group maps to the OAuth scopes specified in the oAuthScopes field of your Custom Application config or Custom View config.

However, you might need more granular access control to fulfill specific business requirements. For example, if your customization manages products, discounts, and orders, and you want a group of users to only manage products and discounts while another group handles orders.

You can define additional permission groups with different access requirements to enable such use cases. For more information, refer to the additionalOAuthScopes field in your Custom Application config or Custom View config.
This feature is available from version 21.21.0 onwards.
In the following example, we're defining two additional permission groups. The group delivery lets users manage incoming orders, while the group promotion lets users work on discount and promotional campaigns.
Custom Application / Custom View configjson
{
  "oAuthScopes": {
    "view": ["view_products", "view_customers"],
    "manage": ["manage_products"]
  },
  "additionalOAuthScopes": [
    {
      "name": "delivery",
      "view": [],
      "manage": ["manage_orders"]
    },
    {
      "name": "promotion",
      "view": [],
      "manage": ["manage_orders", "manage_discount_codes"]
    }
  ]
}

The default permission group is always defined, even when adding additional groups.

When additional groups are defined, the default group can be left empty without specifying any OAuth scopes. However, at least one view-only user permission must be assigned to access the customization.

User permissions

In the Merchant Center, you can assign user permissions to Teams to grant or restrict access to certain parts and functionalities of the Merchant Center. For more information, see User permissions in the Merchant Center.

The same concepts apply to customizations. After your customization is installed in your Organization, you can assign user permissions for your customization to each specific Team.

  • When assigning view-only permission to a Team, only the view_ OAuth scopes are used to authorize API requests.
  • When assigning manage permissions to a Team, both view_ and manage_ OAuth scopes are used to authorize API requests.

For Custom Applications only:

The permission names are unique to each Custom Application, and by default, they derive from the entryPointUriPath, based on the following format: {View,Manage}<EntryPointUriPath>.

Examples:

entryPointUriPathUser permission
channels{View,Manage}Channels
channel-list{View,Manage}ChannelList
channel_list{View,Manage}Channel_List
channel-01{View,Manage}Channel/01
Ultimately, user permissions should be applied and enforced in the actual customization code. For example, to restrict access to certain pages, or to deactivate a button, etc. To learn more about using Permissions during development, see Permissions.

Additional permission groups

When using additional permission groups, the permission name is derived as followed:

For Custom Applications

For Custom Views


The permission name is derived from the entryPointUriPath (same as the default group), plus the group name, based on the following format: {View,Manage}<EntryPointUriPath><GroupName>

entryPointUriPathPermission group nameUser permission
channelswarehouse{View,Manage}ChannelsWarehouse
channel-listwarehouse_west{View,Manage}ChannelListWarehouseWest

The permission name is derived from the group name, based on the following format: {View,Manage}<GroupName>.

Permission group nameUser permission
delivery{View,Manage}Delivery
promotion{View,Manage}Promotion