Image & Video APIs
Menu

Assign roles

Last updated: Sep-04-2025

Use the Permissions API to assign roles to principals (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.

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.

Tip
To learn how to provision roles using SAML SSO, see SAML SSO.

On this page:

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 API 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.
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 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.
Field Applies To Description
operation Top-level Whether to add or remove the listed roles from the principal.
Values: add, remove
Principal object fields: (The principal 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.

See also

✔️ Feedback sent!

Rate this page: