Manage roles

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

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.

• GET /roles sample response: Retrieve a list of roles. You'll need the role's id to inspect details or assign the role to a principal.

Field definitions:

• 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:

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 a policy_statement.
  • When calling GET /roles/{role_id}, each policy listed under the role also includes its policy_statement.

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 or content
• scope_type: account or prodenv
• One or more system_policy_ids
• (Optional) id, name, and description

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

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: