Image & Video APIs
Menu

Role-based permissions overview

Last updated: Jun-30-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.

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 define what actions are allowed. A role includes one or more system policies:

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

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: