Roles

Manage roles.

📄️Create a custom role

Creates a custom role with the name, description and target that you send. The role starts with no permissions, scope or members; add them with the other role routes. Use it to delegate part of administration to people who are not administrators.

📄️Give roles to a user

Gives a user one or more roles in a single call. It handles the built-in Administrator and Reviewer roles and custom roles together. Custom roles the user already holds are skipped and not counted.

📄️Give roles to a group

Gives a group one or more roles in a single call. It handles the built-in Administrator and Reviewer roles and custom roles together. Members of the group receive the roles through the group, and custom roles the group already holds are skipped and not counted. The Administrator role can be given only to a group that is backed by a directory group; otherwise that item counts as failed.

📄️List the names and IDs of all roles

Returns the name and ID of every role, sorted by name, including the built-in Auditors role. Use it to fill a role picker or to look up a role ID. Deleted roles are not included, and the Administrator and Reviewer roles are not listed.

📄️Remove roles from a user

Removes one or more roles from a user in a single call. A signed-in administrator cannot remove their own account from the Administrator role; that item counts as failed. The server reads the list from the request body of this DELETE request, so the body is required. Some HTTP clients and API tools drop the body of a DELETE request; check that yours sends it.

📄️Remove roles from a group

Removes one or more roles from a group in a single call. The Administrator role cannot be removed from a group that the signed-in administrator belongs to; that item counts as failed. The Administrator role can be removed only from a group that is backed by a directory group; otherwise that item counts as failed. The server reads the list from the request body of this DELETE request, so the body is required. Some HTTP clients and API tools drop the body of a DELETE request; check that yours sends it.

📄️List the roles of a user

Returns the roles that a user holds, as a page of results that you can filter by name or description. The built-in Administrator and Reviewer roles appear when the user has them.

📄️List the roles of a group

Returns the roles that a group holds, as a page of results that you can filter by name or description. The built-in Administrator and Reviewer roles appear when the group has them.

📄️Delete a role

Deletes a role. The role no longer appears in role lists, and its members no longer receive the permissions it granted. Use it when a delegated responsibility is no longer needed.

📄️Get a role

Returns one role with its name, description, target and the flags that say whether it covers all activities, credentials, policies, resources or users. It does not return the permissions or the members of the role. Use the other role routes for those.

📄️Update a role

Replaces the stored values of a role with the values you send, such as its name, description and the flags that cover all activities, credentials, policies, resources or users. Fields you leave out are reset to their defaults (false, or 0 for the target), so send the full role. The ID in the body must match the ID in the path. Use it to rename a role or change its description.

📄️Add access policies to a role

Adds access policies to the scope of a role. Role members can then change those policies as far as the permissions of the role allow. Policies already in the scope are skipped.

📄️Remove access policies from a role

Removes access policies from the scope of a role. Role members can no longer change those policies through the role.

📄️Add activities and activity groups to a role

Adds activities or activity groups to the scope of a role. Use it to limit the activities that role members can work with. Entries already in the scope are skipped.

📄️Remove activities and groups from a role

Removes activities or activity groups from the scope of a role. Use it to narrow the activities that role members can work with.

📄️Copy a custom role

Creates a new role from an existing custom role. The copy keeps the permissions, scope and members of the original, but takes its name, description, target and all-items flags from the body, so send the role as it is returned by the get role route with a new name. Built-in roles cannot be copied.

📄️Add credentials and credential groups to a role

Adds credentials, credential groups or host users to the scope of a role. Role members can then use the permissions of the role on those credentials. Entries already in the scope are skipped.

📄️Remove credentials and groups from a role

Removes credentials, credential groups or host users from the scope of a role. Role members can no longer use the permissions of the role on them.

📄️Add users and groups to a role

Gives a role to users, groups, applications or collections that are on the Users & Groups page. Accounts that already hold the role, and IDs that do not exist, are skipped.

📄️Remove users and groups from a role

Takes a role away from the users, groups, applications or collections you send. Use it to stop members from receiving the permissions of the role.

📄️Add users and groups to the scope of a role

Adds users, groups or collections to the scope of a role, which is the set of users the role members can act on. For an Auditors role, it sets whose sessions the members can see. This is separate from the members who hold the role.

📄️Remove users and groups from the scope of a role

Removes users, groups or collections from the scope of a role, which is the set of users the role members can act on. Use it to narrow what members can see or change.

📄️List the permissions of a role

Returns the permissions currently assigned to a role. Each row repeats the role's id, name and description, and gives the permission in permissionId, permissionName and permissionDescription and its permission group in groupId, groupName and groupDescription.

📄️Add permissions to a role

Assigns permissions to a role by their IDs; permissions that the role already has, or that do not exist, are skipped. Terminate Session and Lock Session need Live Session Viewer, which can be sent in the same call. Adding Admin View Read Only also adds the Reporting permission.