Image & Video APIs

Assign roles

Last updated: Jul-21-2025

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

Important
Cloudinary's Roles and Permissions Management is now available as a Beta. This is an early stage release, and while it's functional and ready for real-world testing, it's subject to change as we continue refining the experience based on what we learn, including your feedback. During the Beta period, core functionality is considered stable, though some APIs, scopes, or response formats may evolve. We'll also be expanding the documentation with additional examples, best practices, and implementation tips.

How you can help:

  • Use Roles and Permissions Management in real projects, prototypes, or tests.
  • Share feedback, issues, or ideas with our support team.

Thank you for exploring this early release and helping us shape these tools to best meet your needs.


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.

Tip
See the GET /principal_roles/inspect for specific code examples.

✔️ Feedback sent!

Rate this page: