Image & Video APIs

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:

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.

See also


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's id 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 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

Note
If 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

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:
cld::policy::content::folder::moderate OR cld::policy::global::assets::moderate

View the assets to moderate:
cld::policy::content::folder::view_download OR cld::policy::global::assets_and_folders::view

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:
cld::policy::content::folder::view_download OR cld::policy::global::assets_and_folders::view

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:
cld::policy::content::folder::view_download OR cld::policy::global::assets_and_folders::view

Relate one asset to another Relate assets:
cld::policy::global::asset_relation::create

View the assets you want to relate:
cld::policy::content::folder::view_download OR cld::policy::global::assets_and_folders::view

Move assets between folders Move assets out of the source folder:
cld::policy::content::folder::move_assets

Move assets into the destination folder:
cld::policy::content::folder::add_assets

✔️ Feedback sent!

Rate this page: