Assign roles

Use the Permissions API to assign roles to users, groups, or API keys after you've defined them.

---

Method 1: Assign multiple principals to a role

Use this method when you want to assign the same role to multiple principals, including users, groups, or API keys.

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.

Field	Applies To	Description
operation	Top-level	Whether to add or remove the listed principals from the role. Values: add, remove
Principal object fields:		(Each object in the principals array must include the following fields.)
principal_type	Each role assignment	Type of principal. Values: user, group, apiKey, provisioningKey
principal_id	Each role assignment	Unique ID of the user, group, or key receiving the role.
scope_id	Each role assignment (if scoped to a product environment)	The product environment ID. Find this on the Product Environments page.
policy_parameters	Each role assignment (if the role applies to a specific folder or collection)	ID of the folder or collection the permission applies to.

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 to the specified principal.
• A principals 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.

Field	Applies To	Description
operation	Top-level	Whether to add or remove the listed principals from the role. Values: add, remove
Principal object fields:		(The principals object must include the following fields.)
principal_type	The principal	Type of principal. Values: user, group, apiKey, provisioningKey
principal_id	The principal	Unique ID of the user, group, or key receiving the role.
Role object fields:		(Each object in the roles array must include the following fields.)
id	Each role	ID of the role to apply to the principal.
scope_id	Each role assignment (if scoped to a product environment)	The product environment ID. Find this on the Product Environments page.
policy_parameters	Each role assignment (if the role applies to a specific folder or collection)	ID of the folder or collection the permission applies to.

Example: Assign multiple roles of different types to a principal

---

Inspecting role assignments

Use these endpoints to view current role assignments and permissions:

Endpoint	Use Case
GET /roles/{role_id}/principals	See who has a specific role.
GET /principal_roles	See what roles a user or key has.
GET /principal_roles/inspect	View effective permissions for a user or key (debug access issues).

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.