Use and modify roles for internal users

You can use predefined roles and create custom roles. You can also modify roles by adding security criteria and generic access rights.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

This section describes the predefined roles included with Commerce and how to create and modify custom roles. For information about assigning roles to internal users, see Understand Role-based Access Control.

Use predefined roles

Commerce includes a number of predefined roles. Each predefined role contains a privilege of the same name that provides access to a certain area of the administration interface. For example, the Design role contains the Design privilege, which gives access to the Design page in the administration interface to users assigned the role. You cannot remove the privilege from a predefined role or add a different one to it. If you want a role to contain multiple privileges, you must create a custom role, as described below.

Note that you can add security criteria and generic access rights to a predefined role, but a more flexible approach is to leave the predefined roles as is and add security criteria and generic access rights to custom roles only.

The following table describes the predefined roles and their corresponding privileges. Note that each role and privilege has an ID which is used to identify it in API calls.

Role and Privilege Name	Role ID	Privilege ID	Description
Administrator	adminRole	ora.adminPrivilege	Full access to the Commerce administration interface.
CS Agent	csAgentRole	ora.csAgentPrivilege	Full access to the Agent Console except Manual Adjustments. (Available only if your subscription includes the Agent Console.)
CS Agent Supervisor	csAgentSupervisorRole	ora.csAgentSupervisorPrivilege	Full access to the Agent Console. (Available only if your subscription includes the Agent Console.)
Account Manager	accountManagerRole	ora.accountManagerPrivilege	Full access to the Accounts page. (This feature may not be enabled in your environment.)
Catalog	catalogRole	ora.catalogPrivilege	Full access to the Catalog page. You must also assign the Media privilege if the user will upload images for products, SKUs, and collections.
Dashboard	dashboardRole	ora.dashboardPrivilege	Read access to the dashboard, which is the landing page for the administration interface that users see when they log into Commerce. All privileges that control access to the administration interface allow the user to see the dashboard, but only the Dashboard or Administrator privilege allows a user to see the summary reports there. A user who can see the summary reports on the dashboard needs the Reporting or Administrator privilege to click through to view the full reports.
Design	designRole	ora.designPrivilege	Full access to the Design page.
Marketing	marketingRole	ora.marketingPrivilege	Full access to the Marketing page.
Media	mediaRole	ora.mediaPrivilege	Full access to the Media page.
Operations	operationsRole	ora.operationsPrivilege	Full access to the Service Operations page.
Preview	previewRole	ora.previewPrivilege	Access to the Preview button.
Publishing	publishingRole	ora.publishingPrivilege	Full access to the Publishing page.
Reporting	reportingRole	ora.reportingPrivilege	Full access to the Reports page.
Search	searchRole	ora.searchPrivilege	Full access to the Search page
Settings	settingsRole	ora.settingsPrivilege	Full access to all Settings pages except Access Control, Extensions, Extension Settings, Email Settings, and Web APIs. (Access to those settings is granted by the Administrator privilege.)

Create custom roles

In addition to providing the predefined roles described above, Commerce provides support for creating custom roles. Unlike predefined roles, you can delete custom roles, and you can add privileges to and remove privileges from them.

To create a custom role, use the createAdminRole endpoint in the Admin API, as shown in the following example. As this example shows, when you create a role, you can assign privileges, security criteria, and access rights in the same call. Alternatively, you can create the role and later assign these entities, as described in Modify roles.

POST /ccadmin/v1/adminRoles  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
  "repositoryId": "HomeGoodsMerchandiser",
  "securityCriteria": [
    {
      "id": "securityCriterionHomeGoodsCatalog"
    },
    {
      "id": "securityCriterionHomeGoodsPriceGroup"
    }
  ],
  "accessRights": [
    {
      "repositoryId": "ora.catalogPrivilege"
    },
    {
      "repositoryId": "ar1"
    }
  ],
  "name": "Home Goods Merchandiser"
}

The response is similar to this:

{
    "securityCriteria": [
        {
            "name": "Security Criterion for HomeGoodsPriceGroup",
            "description": "Grants access to HomeGoodsPriceGroup",
            "id": "securityCriterionHomeGoodsPriceGroup"
        },
        {
            "name": "Security Criterion for HomeGoodsCatalog",
            "description": "Grants access to catalog assets of the HomeGoodsCatalog",
            "id": "securityCriterionHomeGoodsCatalog"
        }
    ],
    "name": "Home Goods Merchandiser",
    "repositoryId": "HomeGoodsMerchandiser",
    "description": null,
    "links": [
        {
            "rel": "self",
            "href": "http://www.example.com:7002/ccadmin/v1/adminRoles"
        }
    ],
    "accessRights": [
        {
            "displayName": "Access Right 1",
            "name": "ar1",
            "repositoryId": "ar1",
            "description": "First of several access rights.",
            "id": "ar1",
            "type": "generic"
        },
        {
            "displayName": "Catalog",
            "name": "Catalog",
            "repositoryId": "ora.catalogPrivilege",
            "description": "Catalog Privilege",
            "id": "ora.catalogPrivilege",
            "type": "privilege"
        }
    ],
    "securityCriteriaLastModified": "2021-03-08T21:12:30.047Z",
    "id": "HomeGoodsMerchandiser",
    "category": "Custom"
}

Modify roles

You can use the updateAdminRole endpoint in the Admin API to modify predefined roles or custom roles by adding or removing security criteria and generic access rights. For custom roles, you can also use this endpoint to add and remove privileges.

Note that when you call this endpoint, the body of the request can include the securityCriteria property, the accessRights property, or both. If you include one of these properties in the call, the entities specified in the property replace the ones currently assigned to the role. So, for example, if you include the securityCriteria property to add a security criterion to a role, the value of the property should include all of the security criteria that are currently assigned to the role, in addition to the security criterion you want to add; if you specify only the new criterion, the existing criteria will be removed from the role. Similarly, if you include the accessRights property to add a privilege or a generic access right, the value of the property should include the privileges and generic access rights that are currently assigned to the role. If you add a generic access right to a predefined role, be sure to include the role's privilege in the accessRights property, or the request will be rejected.