OAuth scopes and user permissions

Learn about applying permissions to your customizations.

OAuth scopes

Customizations can use any of the available Composable Commerce APIs. This allows you to extend the functionality and build custom features for any of the Composable Commerce APIs and the Merchant Center. Therefore, customizations must specify the list of OAuth scopes needed for 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.

These OAuth scopes must be specified 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.

In this scenario, more than one permission group (the default one) is needed to fulfill the access requirements.

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 promotion 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" permission 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:

`entryPointUriPath`	User 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:

Custom Applications

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>

`entryPointUriPath`	Permission group name	User permission
`channels`	`warehouse`	`{View,Manage}ChannelsWarehouse`
`channel-list`	`warehouse_west`	`{View,Manage}ChannelListWarehouseWest`

Custom Views

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

Permission group name	User permission
`delivery`	`{View,Manage}Delivery`
`promotion`	`{View,Manage}Promotion`