Manage roles
Last updated: Jul-21-2025
Cloudinary roles define what users, groups, and API keys can access and do across your account. Managing roles via the Permissions API allows you to create, update, and delete custom roles programmatically, so you can scale permissions consistently without assigning individual policies one by one.
On this page, you’ll learn how to:
- Retrieve roles and system policies
- Manage custom roles
- Considerations for planning roles effectively
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.
- Permissions API reference: Full list of endpoints and schemas
- System roles and policies: A list of all system roles and system permission polices provided by Cloudinary
- Assign roles: How to assign roles via API
- Define custom policies: Create and apply policies outside of roles
- Role management in the Console: UI-based role management
Retrieve roles and system policies
Use these endpoints to review available roles and system policies in your account.
Role details
Use these endpoints to list and inspect both system and custom roles, and to review which system policies each role includes. This is useful when planning which roles you want to assign and figuring out whether you need to create additional custom roles.
Endpoint | Use Case |
---|---|
GET /roles |
List all roles. You can filter by management_type=system or management_type=custom . |
GET /roles/{role_id} |
View the policies included in a specific role |
-
GET /roles
sample response: Retrieve a list of roles. You'll need the role'sid
to inspect details or assign the role to a principal.
Field definitions:
Field | Description |
---|---|
id |
The role’s unique identifier. Use this when assigning the role programmatically. System roles use the cld::role:: prefix. |
name |
Display name for the role, as shown in the Console. |
description |
Summary of the permission the role grants. |
management_type |
Predefined roles are "system" and roles that you create are "custom" . |
permission_type |
Indicates the level at which the role applies, either "global" or "content" . |
scope_type |
Specifies the scope of the role. Global roles can be "account" or "prodenv" (product environment). Content roles are always "prodenv" . |
created_at , updated_at
|
Timestamps indicating when the role was created and last updated (Unix epoch format). |
-
GET /role
sample response: Retrieves all policies included in a specific role, providing a more detailed view of what that role can do.
For a list of all system roles, see System role reference.
System policy details
You can retrieve a comprehensive list of system policies using GET /policies/system
.
The policy object returned by GET /policies/system
follows the same structure as the policies listed in the policies array returned by GET /roles/{role_id}
. This shared structure makes it easier to reference system policies when creating or reviewing custom roles.
Each policy includes the following fields:
Field | Description |
---|---|
id |
The unique system_policy_id used when referencing this policy in roles. |
name |
The display name of the policy, shown in the Console. |
description |
A summary of what the policy allows, including relevant UI and API capabilities. |
scope_type |
Defines the scope at which the policy applies. Typically "prodenv" for product environments. |
permission_type |
Indicates whether the policy applies globally or in a more granular context ("global" or "content" ). |
policy_statement |
The underlying Cedar policy expression that defines the permission logic. For more information, see Understanding the policy_statement. |
policy_parameters |
Relevent only if the permission_type is content . Specifies whether the policy applies to a folder_id or a collection_id . |
created_at , updated_at
|
Unix timestamps indicating when the policy was created and last updated. |
For a list of all system policies, see System policy reference.
Understanding the policy_statement
Each system policy includes a policy_statement
field, which defines the actual access rule in Cedar, an expressive, logic-based language designed for fine-grained authorization. This statement determines what action the policy allows, and on which resources, and under what conditions.
Structure and purpose
The policy_statement
defines the core logic of a policy. It contains one or more permit
rules, each made up of the following components:
principal: The actor (such as a user, group, or API key) that receives the permission.
action: The operation the policy allows (e.g.,
read
,update_settings
,delete
).resource: The object the action targets, typically a content instance or feature (e.g.,
Cloudinary::Asset
,Cloudinary::Folder
,Cloudinary::Feature::"cld::global::ml::access"
).when clause (relevant for folder and collection roles only): A condition that determines when the permission applies (e.g., the asset exists within a certain folder).
You define both the principal and the folder or collection ID (for the when
clauses) when you assign the role. The assignment implicitly specifies the principal, and you pass the folder or collection through the policy_parameters field.
Example
Here's a policy_statement
from a policy that allows viewing assets within a specific folder and its subfolders:
This statement means: The principal can read folders or assets, but only if they exist within the specified folder (
<folder_id>
).-
Where it appears:
- When calling
GET /policies/system
, each returned system policy includes apolicy_statement
. - When calling
GET /roles/{role_id}
, each policy listed under the role also includes itspolicy_statement
.
- When calling
This consistency allows you to clearly see and reason about the exact behavior of each policy, whether you're applying it directly or as part of a role.
Manage custom roles
Use these endpoints to manage custom roles for your account or product environments.
Create a custom role
Use POST /roles/custom
to define a role and include the system policies it should grant.
You must specify:
-
permission_type
:global
orcontent
-
scope_type
:account
orprodenv
- One or more
system_policy_ids
- (Optional)
id
,name
, anddescription
Global roles apply to all content or account-level features. Content roles apply to specific folders or collections and require policy_parameters
when assigning.
Example 1: Create a global role to manage uploads
Example 2: Create a content role for folder access
Example 3: Create an account-level role for admin tasks
scope_type
is prodenv, you must specify the product environments when assigning the role. You can assign to "all" environments or a specific list of product environment IDs.Update or delete a custom role
Update a role: PUT /roles/custom/{role_key} You can update the role’s name, description, or system policies.
Delete a role: DELETE /roles/custom/{role_key} Roles can only be deleted if they aren’t currently assigned.
Considerations for planning roles effectively
Assignment considerations
You can assign roles to groups, users, product environment API keys, and account API keys.
You can assign all role types to any of these entities. However, some assignments may have no practical effect, depending on scope or context:
-
Scope matters: If you assign an account-level role to a product environment API key, the permissions won’t apply.
For example, if you try to grant product environment API keys permission to provision users via the Provisioning API, the assignment won't have any effect.
-
UI-based permissions: Some roles grant access to areas of the Console, such as viewing dashboards or reports.
Assigning these to an API key won’t have any effect, since API keys can’t interact with the UI.
See the full list of system permission policies for details on which permissions are available by scope and applicable to each entity type.
Actions that require multiple permissions
Some tasks require multiple permissions to enable. If a user doesn't have all the permissions listed for that action, they won't be able to perform it. Make sure the roles you create contain all the listed permissions to perform these actions:
Action | Required System Policies |
---|---|
Use Moderation tab to moderate assets | Access the moderation page:cld::policy::global::moderation_queue::access Moderate all assets or assets in folders: View the assets to moderate: |
Add assets to (non-dynamic) collections | Add assets to all collections or specific collections: cld::policy::content::collection::add_assets OR cld::policy::global::collections::manage View the assets to add to collections: |
Remove assets from (non-dynamic) collections | Remove assets from all collections or specific collections: cld::policy::content::collection::remove_assets OR cld::policy::global::collections::manage View assets to remove from collections: |
Relate one asset to another | Relate assets:cld::policy::global::asset_relation::create View the assets you want to relate: |
Move assets between folders | Move assets out of the source folder: cld::policy::content::folder::move_assets Move assets into the destination folder: |