Image & Video APIs
Menu

Role-based permissions overview

Last updated: Jul-21-2025

Cloudinary's role-based permission system lets you control what users, groups, and API keys can do across your account and product environments. Permissions are managed through roles, which contain one or more policies that define specific capabilities.

This page introduces key concepts shared across the Console and Permissions API.

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.

On this page:

Who you can assign roles to

You can assign roles to the following entities:

  • Users: A named user with login access to the Console.
    Roles control which areas of the Console the user can access.
  • Groups: A group of users.
    Roles assigned to a group apply to all users within it.
  • Product environment API keys: Used for programmatic access to a product environment.
    Roles determine the actions the key can perform via the Admin and Upload APIs.
  • Account API keys: Used to perform account administrative tasks, e,g. user provisioning.
    Roles determine the actions the key can perform via the Provisioning & Permissions APIs.

Key role attributes

Each role has two important attributes:

  • Scope type: Where the role applies.

    • account: Scope applies at the Cloudinary account level (e.g., account security, user management, billing, etc.).
    • prodenv: Scope applies to a specific product environment (e.g., managing folders, assets, collections, product environment settings, etc.)
      Note
      In the Console, the scope type is referred to as Permission level.

  • Permission type: What the role governs (e.g., global permissions, or permissions on specific folder or collection instances)

Permission Type Description Scope Type
Global Apply across all content instances (e.g., all folders, all assets) or to high-level account-wide features (e.g., user management, account security). account or prodenv
Folder Controls actions on specific folders and their assets prodenv
Collection Controls collaboration and visibility for specific collections in the Media Library prodenv

System roles vs. custom roles

Each role is either a system or custom management type. Both types use system policies, which are predefined permission rules defined by Cloudinary.

  • System roles are predefined by Cloudinary and include a fixed set of system policies. They can't be edited but are ideal for consistent, quick setup. You can assign them to users, groups, or API keys. For the full list of system roles that Cloudinary provides and what each role allows, see System roles and policies.

  • Custom roles are defined by you. You choose the name, description, and which system policies to include. This lets you tailor roles to your team's exact needs.

Role Type Description
System role Predefined by Cloudinary. Can't be modified. Useful for quick setup.
Custom role Created by you. You define the name, description, and permission policies it includes.

Note
If system policies don't meet your requirements, you can define custom policies and assign them directly to principals (e.g., users or API keys), without using roles. This method is available via the API, but may lead to unexpected UI behavior. See Custom permission policies for details.

Policies and permissions

Policies allow users, groups, or API keys to perform specific actions. A role includes one or more system policies, which:

  • Cloudinary defines (you can't change them)
  • Apply either globally or to specific content instances (such as a folder)

Each system policy includes a policy_statement, a Cedar expression that defines exactly what the policy allows. You can view this statement in the Permissions API (see Understanding the policy_statement) and in the Role Management page of the Console Settings (see View role permissions).

Note
In the Console, system policies are referred to as permissions.

Both system and custom roles consist of one or more system policies. Assigning a role to a user, group, or API key applies all of the policies included in that role.

If the system policies that Cloudinary provides don't meet your needs, you can create custom policies using the API. You can't include custom policies in roles, and you must assign them directly to users, groups, or API keys.

Policy Type Applies To Created By Assignment method
System Policy Users, groups, API keys Cloudinary Included in roles and assigned to principals via roles
Custom Policy Users, groups, API keys You (via API) Assigned directly to principals; not usable in roles

Important
Custom policies may produce unexpected results, especially in the UI.

Common fields glossary

Field Description
scope_type account or prodenv. Indicates where the role or policy applies.
scope_id Required if scope_type is prodenv. Specifies the target product environment.
permission_type global or content. Global policies apply broadly; content policies apply to specific content instances.
policy_parameters Used only for content roles. Defines what folder or collection the role applies to.

Which method to use?

Goal Method
View all system policies GET /policies/system
Create a custom role POST /roles
View all roles GET /roles
Assign one role to multiple users PUT /roles/{role_id}/principals
Assign multiple roles to one user PUT /principal_roles
View a user or key's current roles GET /principal_roles
View all users with a specific role GET /roles/{role_id}/principals
Inspect effective access GET /principal_roles/inspect

Next steps

✔️ Feedback sent!

Rate this page: