Image & Video APIs
Menu

Roles and Permissions overview

Last updated: Apr-20-2026

This guide describes the Roles and Permissions system. For details on all roles available in the legacy system, see Role-based permissions.

Which permissions system do you have?
Use the rollout schedule to find out:
  • Enterprise accounts: Broad Enterprise migration hasn't started yet. If your team hasn't already been moved with Cloudinary's help, you're still on the legacy system.
  • Existing free and paid accounts: Migration starts May 12, 2026.
  • New free accounts (created since February 2026): You may already have the new system.

You can confirm which permissions system you have. Open Console Settings and look for Role Management. If it's listed, your account is on Roles and Permissions. If it isn't listed, you're still on the legacy permissions model.

Global role management

The Roles and Permissions system provides more granular, flexible access control than the legacy system.

Overview

For Free plan customers:
The Permissions API isn't available on the Free plan. You can manage roles and permissions via the Console only and assign folder roles to API keys and other principals programmatically via the Admin API.

On this page:

Cloudinary's role-based permission system with granular permissions lets you control what principals (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.

Who you can assign roles to

Principals are actors in your Cloudinary account and product environments that you can assign roles to.

They can be:

  • Users: Named users with login access to the Console.
    Roles control which areas of the Console a user can access.
  • Groups: Groups 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 Management Keys: Used to perform account administrative tasks, e,g. user provisioning.
    Roles determine the actions the key can perform via the Provisioning and Permissions APIs.

Note
Roles don't apply to the account root management key or the product environment root API key since these keys automatically have full administrative permissions for their scope.

Key role attributes

Cloudinary supports three types of roles: global, folder, and collection.

Each type of role is scoped to either the account or one or more product environments, and is relevant to a different set of principals:

Role Type Permission Level (Scope) Description Applies to System Roles
Global Account Controls permissions for account-wide features, such as user management and billing. Users, groups, and account management keys View predefined global account-level roles
Global Product environment Controls permissions for specific capabilities (such as upload presets and transformations), or across all folders and collections in a product environment. Users, groups, and product environment API keys

Note: Some global product environment roles also apply to account management keys

 View predefined global product environment-level roles
Folder Product environment Controls permissions for specific folders and their assets. Users, groups, and product environment API keys

Note: Folder roles can only be assigned to API keys [programmatically].(permissions_assign_roles_api#assign_folder_roles_via_the_admin_api)

 View predefined folder roles
Collection Product environment Controls permissions for specific collections in the Media Library. Users and groups only View predefined collection roles

How to manage roles:

How to assign roles:

Tip

API vs. Console terminology:

  • In the API:
    • The permission_type parameter accepts global or content (which covers both folders and collections).
    • The scope_type parameter accepts account or prodenv.
  • In the Console:
    • Role type can be Global, Folder, or Collection.
    • Permission level can be Account or Product environment.

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 principals. For the full list of system roles that Cloudinary provides and what each role allows, see System roles and policies list.

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

For Free plan customers:
Custom roles aren't available on the Free plan. You can use system roles and access bundles.
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 principals 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 principals.

Policy Type Applies To Created By Assignment method
System Policy All principals (users, groups, API keys) Cloudinary Included in roles and assigned to principals via roles
Custom Policy All principals (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.

Quick setup with access bundles (Console only)

For faster user onboarding, the Console offers access bundles, predefined combinations of system roles designed for common user types (Master Admin, Admin, Technical Admin, Billing, Reports, Media Library Admin, and Media Library User).

Access bundles streamline the invitation process for organizations that don't need granular role customization. When inviting new users in the Console, you can select an access bundle instead of manually assigning individual roles. Each bundle translates into a set of roles applied at the appropriate level — account or product environment — across all product environments.

For full details on access bundles and user invitation workflows, see Define access when inviting new users.

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 such as folders or collections.
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:

one star two stars three stars four stars five stars