Documentation

OAuth Scopes and user permissions

OAuth Scopes

Custom Applications 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 Applications must specify the list of OAuth Scopes needed by the application.

For example, if you are developing a Custom Application 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 Application would require the following OAuth Scopes:

  • view_products, view_customers
  • manage_products

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

custom-application-config.jsonjson
{
  "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 Application 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 Application config.

However, you might need more granular access control to fulfil specific business requirements. For example, if your Custom Application manages products, discounts and orders, you might want only a group of users to manage products and discounts while another group of users handles orders.
In this kind of scenario a single permission group (the default one) is not enough as you would need multiple permission groups fulfil the access requirements.

To enable such use cases, you can define additional permission groups that have different access requirements. See additionalOAuthScopes field in the Custom Application config.

This feature is available from version 21.21.0 onwards.

In the following example, we are 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-application-config.jsonjson
{
  "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 not adding additional groups.

When additional groups are defined, the default group can be left "empty", without specifying any OAuth Scopes.

Even so, remember that the "view-only" user permission must be enabled to allow access to the Custom Application.

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 Applications as well. Once your Custom Application has been installed in your Organization, you can assign user permissions for your Custom Application to each specific Team.

Each Custom Application 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.

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

Here are some examples:

entryPointUriPathUser permission
avengers{View,Manage}Avengers
the-avengers{View,Manage}TheAvengers
the_avengers{View,Manage}The_Avengers
avengers-01{View,Manage}Avengers/01
avengers_01{View,Manage}Avengers_01

When using additional permission groups, 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>

Here are some examples:

entryPointUriPathPermission group nameUser permission
avengersthor{View,Manage}AvengersThor
the-avengersiron-man{View,Manage}TheAvengersIronMan

Ultimately, user permissions should be applied and enforced in the actual Custom Application 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.