This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

OAuth Scopes and user permissions

OAuth Scopes

Custom Views 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, Custom Views must specify the list of OAuth Scopes needed for the data fetching requirements.

For example, if you are developing a Custom View to manage Channels you would probably need the OAuth Scopes view_products and manage_products. On top of that, you might decide to also view Customers information.
To fulfill these requirements, your Custom View would need the following OAuth Scopes: view_products, view_customers and manage_products.

These OAuth Scopes must be specified in your Custom View config, using the oAuthScopes field.

custom-view-config.mjsJavaScript
const config = {
"oAuthScopes": {
"view": ["view_products", "view_customers"],
"manage": ["manage_products"]
}
// ...
}

Notice here how the OAuth Scopes are grouped by the two fields view and manage.

This grouping determines the mapping and relation between OAuth Scopes and user permissions.

Permission groups

Every Custom View 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 the Custom View config.

However, you might need more granular access control to fulfill specific business requirements. Suppose your Custom View 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. See additionalOAuthScopes field in the Custom View config.

In the following example, we're defining two additional permission groups. The group delivery allows users to manage incoming orders, while the group promotion enables users to work on discount and promotion campaigns.

custom-view-config.mjsJavaScript
const config = {
"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.

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. See user permissions in Merchant Center for more information.
The same concepts apply for Custom Views as well. Once your Custom View has been installed in your Organization, you can assign user permissions for your Custom View to each specific Team.

Each Custom View gets unique "view" and "manage" permissions.

  • 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.

Additional permission groups

When using additional permission groups, the permission name is derived from the group name, based on the following format: {View,Manage}<GroupName>

Here are some examples:

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

Ultimately, user permissions should be applied and enforced in the actual Custom View code. For example to restrict access to certain pages, or to deactivate a button, etc.

To learn more about it, head over to the Permissions in the development section.