Assign roles

This guide describes the Roles and Permissions system. For details on all roles available in the legacy system, see Role-based permissions.

Overview

You can assign all roles defined in your account to principals, including users, groups, and API keys.

• Use the Permissions API to assign global, folder, and collection roles.

  For Free plan customers:

  The Permissions API isn't available on the Free plan. You can manage roles and permissions via the Console only and assign folder roles to API keys and other principals programmatically via the Admin API.

• Use the Admin API to assign folder roles.

Assign roles via the Permissions API

Enterprise customers can use their account management keys to manage and assign all roles via the Permissions API.

Base URL and authentication

All Permissions API endpoints on this page use the following base path:

Replace ACCOUNT_ID with your actual account ID.

Find your account ID and credentials in the Account Management Keys page of the Console Settings.

Method 1: Assign a role to multiple principals

Use this method when you want to assign the same role to multiple principals.

Endpoint:
PUT /permissions/roles/{role_id}/principals

The request body should include:

• An operation field (at the top level) that defines whether to add or remove the listed principals.
• A principals array containing one or more principal assignment objects.

Example 1: Assign principals to an account role

Example 2: Assign a global role across different product environments

Example 3: Assign a content role to different folders

Example 4: Remove a principal from a role

Method 2: Assign roles to a principal

Use this method to assign multiple roles of different permission types and scopes (account, product environment, global, and content) to a single principal:

PUT /permissions/principal_roles

The request body should include:

• An operation field (at the top level) that defines whether to add or remove the roles from the specified principal.
• A principal object specifying the principal to assign roles to.
• A roles array containing one or more role assignment objects. Each object may optionally include scope_id and/or policy_parameters, depending on the role.

Example: Assign multiple roles of different types to a principal

Inspecting role assignments

Use these endpoints to view current role assignments and permissions:

View effective permissions

Use the GET /principal_roles/inspect endpoint to check which roles or permission policies apply to a user, group, or key, based on specific content, product environments, or scopes.

This endpoint is especially useful for debugging access issues, such as:

• Why a user can or can't access a folder or collection

• Whether a key has permission to perform an action in a specific product environment

• Confirming inherited or global role assignments

You can filter by:

• Principal: principal_type and principal_id

• Scope: scope_type (account or prodenv), and scope_id if needed

• Content instance: folder_id, collection_id, or asset_id

To inspect broad access, you can also use special values like folder_id=all.

Assign folder roles via the Admin API

You can use the Admin API to assign folder roles to users, groups, and API keys. For full details, see folder_operations in the Admin API.

The folder_operations endpoint provides an alternative way to assign folder roles alongside the Permissions API.

You currently can't assign folder roles to API keys in the Console, so the only way to do so is programmatically.