Granting Privileges

The operation of granting privileges is not to be taken lightly, as insufficient privileges can hinder task accomplishment, while inadequate or unnecessary privileges could lead to accidents or misuse. When allowed to delegate powers, you should have a good understanding of how the Coveo Cloud privilege system works and be well aware of the implications of each choice you make. In this regard, Coveo strongly recommends thoroughly reading its privilege documentation before granting privileges or editing a privilege set, and enforcing the principle of least privilege, i.e., granting just enough privileges for the grantee to perform their task (see Privilege Management and Principle of Least Privilege).

Moreover, to help you use the privilege system safely and efficiently, this page guides through the process of granting privileges to API keys or to other users of the Coveo Cloud administration console. Coveo encourages you to use this page as a reference until you are fully comfortable managing privileges.

To grant privileges to an existing group, you must have the privilege to edit this group (see Groups Domain). To create a new group and grant it privileges in the process, you need the privilege to create groups. Moreover, for each privilege you want to grant, you also need to have the target access level yourself (see Confirm Your Options).

Select a Grantee

Depending on your intention, the privilege grantee is either an API key or a group of users. For instance, if you want to grant an application the privilege to query your Coveo index, you should create an API key with the appropriate privileges for the application to use when communicating with Coveo Cloud (see Adding and Managing API Keys). Conversely, if you want to grant Coveo Cloud users certain privileges, you should opt for a group of one or more users.

If you choose to grant privileges to a group of users, you have several options:

  • You can create a new group from scratch and grant it the desired privileges (see Create a New Group). This is generally the easiest and safest option.
  • You can duplicate the group with the privilege set closest to the desired set and edit the privilege set of the copy (see Duplicate a Group and Edit a Group). You can then add the users to this new group.
  • You can pick the unused built-in group with the privilege set closest to the desired set, and then edit these privileges to tailor them as needed (see Edit a Group).
  • You can review the privileges granted to the built-in groups and decide to use one of those groups as it is, without making any changes (see Built-In Groups). This is however not recommended if you want to enforce the principle of least privilege (see Principle of Least Privilege).

For users in more than one group, the highest access level granted for each domain applies (see Remark: Conflicting Access Levels).

Determine the Privileges to Grant

Once you have selected a grantee, you must determine which privileges you want to grant them. To do so, you should make a list of the operations the grantee should be allowed perform, the information they should be able to access, etc., and of the domains and access levels to which these actions are associated.

You need an API key to send analytics events to Coveo Usage Analytics (Coveo UA) and to view usage analytics reports. This API key therefore needs two privileges in the Analytics service:

  • Push on the Analytics data domain.
  • View on the Reports domain.

The Privileges Reference page contains a list of all available domains and access levels, and the associated capabilities.

You can also find a list of the privileges required for certain actions in the Coveo Cloud documentation. This information is especially important since a View or Edit access level on a domain alone is not necessarily sufficient to view or edit the content of the corresponding page, despite most domain names being similar to the names of the Coveo Cloud administration console pages (see Coveo Cloud V2 Administration Console). Other privileges may be required to view or edit the content of an administration console page. So, if you have decided that you want a group of users to access a specific page of the Coveo Cloud administration console, you can review a list of the privileges required to perform actions in this page.

  1. In the Coveo Cloud administration console, in the navigation menu on the left-hand side, click the desired page.
  2. At the top of the page, click the question mark next to the page title. This should open the corresponding documentation page.

    Opening the page documentation

  3. On the right-hand side of the documentation page, at the bottom of the In This Article section, click Required Privileges. This link leads you to a list of the privileges required to perform certain actions in the desired administration console page.

    Accessing the Required Privileges documentation section

Inadequate or unnecessary privileges can lead to accidents or misuse. Coveo therefore strongly recommends thoroughly reading its privilege documentation before granting privileges or editing a privilege set, and enforcing the principle of least privilege, i.e., granting just enough privileges for the grantee to perform their tasks (see Privilege Management and Principle of Least Privilege).

Confirm Your Options

Before you can grant privileges, you must make sure that your own privilege set allows you to give the desired privileges. If you are a Coveo Cloud administrator, you can edit everything in the administration console and therefore grant all privileges (see Built-In Groups). If you are not, you must ensure that your own privilege set does not prevent you to grant the desired privileges. Should they be insufficient, you must ask a Coveo Cloud user with a sufficient privilege set (e.g., an administrator) to either grant you the required privileges, or to give the target grantee the desired privileges themselves.

For each domain, the access levels you can grant to a group or API key depend on the access level you have yourself, as well as the level that was last saved, if you are editing an existing group (see Adding and Managing Groups and Adding and Managing API Keys). In short, the list of access levels from which you can choose generally consists of the last saved access level, the access level you have, and the access levels of lesser importance than those, i.e., access levels that represent fewer abilities (see Understanding Privileges).

The following table summarizes the available access levels for a domain, assuming you are allowed to edit the group or API key of which you want to modify the privilege set (see Understanding Resource Access):

Access level you have Last saved access level Access levels you can grant the group or API key
None None N/A (you cannot change the access level)
None View all None or View all
None Custom None, View all, or Custom1
None Edit all None, View all, or Edit all
View all None, View all, or Custom None or View all
View all Edit all None, View all, or Edit all
Custom None, View all, or Custom None, View all, or Custom
Custom Edit all None, View all, Custom, or Edit all
Edit all Any None, View all, Custom, or Edit all

Note 1: In this scenario, if you select Custom, you cannot view the list of the resources available in the Coveo Cloud organization, as you do not have the privilege to view these resources (see Understanding the Custom Access Level).

The table above also applies for domains that do not offer the Custom access level option, such as Fields (see Fields Domain).

You are allowed to edit the Content Viewers group. This group has the View access level for the Fields domain, while you have Edit. When changing the group’s access level for this domain, you can choose from your access level, those of lesser importance, and the original group’s access level, i.e., Edit, View, or no access at all.

  • After switching from a higher access level to a lower level, you may not be able to grant the higher level again if you are not yourself granted this higher access level.

    You are allowed to edit groups and to view fields, and you want to revoke the privilege of the Content Manager group to edit fields. Since your access level options for the Fields domain consist in the last saved access level (Edit), the access level you have (View), and the access levels of lesser importance than those (no access), you can choose from Edit, View, and no access at all. You switch the Fields domain access level from Edit to View and save, so the last saved access level is now View. Then, the next time you edit the privileges of the Content Manager group, your access level options for Fields are only View and no access at all, since you do not have the Edit access level on Fields yourself.

  • Similarly, if only one of your groups grants you a higher access level on a certain domain and you edit this group’s privilege set to select a lower access level for this domain, you will permanently lose the higher access level after saving.

    You are a member of several groups, but only the Group Managers group grants you the privilege to edit groups. You no longer want the Group Managers group to be able to edit groups, so you switch its Groups access level to View. Once you save, you lose your privilege to edit groups and are only able to view them, as Group Managers was the only group that granted you the Edit access level for the Groups domain.

Grant Privileges

Once you have a list of the privileges you want to grant and have ensured that your own privilege set allows you to grant them, you can proceed in the Privileges tab (see Determine the privileges to grant and Navigating the Privileges Tab):

  1. In the Coveo Cloud administration console, depending on your grantee, access the Groups or API Keys page (see Select a Grantee).
  2. Create a group or API key, or select one to edit.
  3. In the Configuration tab, enter or review the basic resource information.
  4. In the Privileges tab:
    1. Use the menu on the left to navigate the services (see Navigating the “Privileges” Tab). For each domain in each service, select the desired access level (see Determine the Privileges to Grant). Alternatively, you can use the Preset menu to quickly and broadly grant privileges, and then edit only the desired privileges (see About the Preset Menu).
    2. If editing an existing group or resource, you can discard any change with which you are not satisfied (see Discard Changes).
    3. If your grantee is a group, ensure to include the minimum privilege so that the grantee can access the Coveo Cloud administration console (see Minimum Privilege).
    4. Make sure to review any warning that appears (see Warnings).
  5. In the Access tab, review which groups or API keys can edit the resource (see Understanding Resource Access).
  6. At the bottom of the panel, click Save.
  7. If the grantee is a group, invite members in the group or review the list of members (see Members Tab).

Discard Changes

When editing the privileges of a grantee, a Discard changes button (Discard changes button) appears on the right-hand side of the domain rows you modified, allowing you to revert all changes made for this domain (see Navigating the Privileges Tab). In the service menu on the left-hand side, a number between parentheses indicates the number of edited domains in the corresponding service that will be saved when you click Save.

There are two edited domains in the Content service.

Two unsaved privileges in the Content service

Minimum Privilege

The View access level on the Organization domain in the Organization service is required for a group of users to access your organization in the Coveo Cloud administration console (see Organization Domain). It is the minimum privilege required—without it, they cannot access any information relatively to your organization, even if they have other privileges.

For instance, when your Coveo Cloud organization members do not have the minimal View access level on the Organization privilege and try to log in to the Coveo Cloud administration console, they get the following message:

Insufficient privileges

You currently have insufficient privileges to access the Coveo Cloud administration console of the [OrganizationName] organization. Contact an administrator of the [OrganizationName] organization to change your privileges, or select an organization to which you have access through the Coveo Cloud administration console.

API keys, however, do not require this privilege to access your organization content.

Warnings

A yellow circle in the service menu indicates that there is a warning message regarding a change you made. In the list of domains in this service, hover over the yellow icon to display the warning. Coveo recommends reviewing the privilege documentation in the Privilege Reference page before saving.

Warning indicators

What’s Next?