> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and Permissions overview


[new-permissions-link]: permissions_overview
[old-permission-link]: user_provisioning#role_based_permissions
[access-bundles-link]: permissions_overview#access_bundles

This guide describes the Roles and Permissions system. For details on all roles available in the legacy system, see [Role-based permissions](user_provisioning#role_based_permissions).

> **INFO**:
>
> :title=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](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/roles_interface.png "thumb: w_800,dpr_2, width:800, with_code:false, with_url:false, popup:true")
> The Roles and Permissions system provides more granular, flexible access control than the legacy system. 

> * For a quick comparison, see [Roles and Permissions vs. legacy](dam_admin_users_groups#roles_and_permissions_vs_legacy). 

> * If your account is being migrated, see [Migrating to Roles and Permissions](permissions_migration) to understand what changes.

## Overview
> **NOTE**: :title=For Free plan customers:

The Permissions API isn't available on the Free plan. You can [manage roles and permissions](dam_admin_permissions) via the [Console](https://console.cloudinary.com/app/settings/role-management) only and assign folder roles to API keys and other principals programmatically via the [Admin API](permissions_assign_roles_api#assign_folder_roles_via_the_admin_api).

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](account_settings#root_account_management_key) or the [product environment root API key](product_environment_settings#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:

{table:class=no-borders overview wide-3}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](permissions_system_roles_policies#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](permissions_system_roles_policies#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](permissions_system_roles_policies#folder_roles) |
**Collection** | Product environment | Controls permissions for specific collections in the Media Library. | **Users** and **groups** only | [View predefined collection roles](permissions_system_roles_policies#collection_roles) |

**How to manage roles:**

* [Via the Console](permissions_manage_roles_ui#manage_roles_with_granular_permissions) 
* [Via API](permissions_manage_roles_api) (Enterprise plans only)

**How to assign roles:**

* [Via the Console](dam_admin_role_management#assign_roles)
* [Via API - global roles](permissions_assign_roles_api) (Enterprise plans only)
* [Via API - folder roles](permissions_assign_roles_api#assign_folder_roles_via_the_admin_api) (All plans)

> **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](permissions_system_roles_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.
> **NOTE**: :title=For Free plan customers:

Custom roles aren't available on the Free plan. You can use [system roles](dam_admin_permissions#system_and_custom_roles) and [access bundles](dam_admin_permissions#quick_setup_with_access_bundles).

{table:class=no-borders overview} 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](permissions_custom_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](https://www.cedarpolicy.com/en) expression that defines exactly what the policy allows. You can view this statement in the Permissions API (see [Understanding the policy_statement](permissions_manage_roles_api#understanding_the_policy_statement)) and in the Role Management page of the Console Settings (see [View role permissions](permissions_manage_roles_ui#view_role_details)).

> **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](permissions_custom_policies) using the API. You can't include custom policies in roles, and you must assign them directly to principals.

{table:class=no-borders overview} 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  | 

> **INFO**: 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](permissions_manage_roles_ui#define_access_when_inviting_new_users).

## Common fields glossary

{table:class=no-borders overview} 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?

{table:class=no-borders overview}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

* [Manage roles and permissions in the Console](permissions_manage_roles_ui)
* [Manage roles programmatically using the API](permissions_manage_roles_api)
* [View all system roles and policies](permissions_system_roles_policies)
* [Define custom Cedar policies](permissions_custom_policies)