# OAuth scopes and user permissions

Learn about applying permissions to your customizations.

## OAuth scopes

You can extend the functionality of the Merchant Center by using any of the 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](/api/projects/channels.md), you would need the OAuth scopes `view_products` and `manage_products`. In addition, you might decide to also view [Customers](/api/projects/customers.md) 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](/api/scopes.md) in your [Custom Application config](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md) or [Custom View config](/merchant-center-customizations/tooling-and-configuration/custom-view-config.md) using the `oAuthScopes` field:

```json title="Custom Application / Custom View config"
{
  "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.

### Configuration scope for development and production

The `oAuthScopes` field in your configuration file serves different purposes depending on your environment:

- **Local development**: during development, you define OAuth scopes in your configuration file to enable quick iteration without requiring application registration in the Merchant Center. Local configuration does not require administrative setup.
- **Production**: for deployed applications, permissions are managed through the Merchant Center UI. You can keep your local configuration file as the source of truth and use the [`config:sync`](/merchant-center-customizations/tooling-and-configuration/cli.md#configsync) command to synchronize it with your deployed application, automating permission updates.

### 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](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md) or [Custom View config](/merchant-center-customizations/tooling-and-configuration/custom-view-config.md).

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](/merchant-center-customizations/tooling-and-configuration/custom-application-config.md) or [Custom View config](/merchant-center-customizations/tooling-and-configuration/custom-view-config.md).

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.

```json title="Custom Application / Custom View config" highlightLines="6"
{
  "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](/merchant-center/user-permissions.md).

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:

| `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](/merchant-center-customizations/development/permissions.md).

### Additional permission groups

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

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

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

## Related

For more information on what to do next, we recommend the following sections:

- **[Applying user permissions](/merchant-center-customizations/development/permissions.md)**

  Learn more about applying user permissions in your customization.

## Related pages

- [Area overview page with navigation](/merchant-center-customizations.md)
- [Next page: Merchant Center Proxy Router](/merchant-center-customizations/concepts/merchant-center-proxy-router.md)
- [Search documentation and API specs](/search.md)