Image & Video APIs

Role management in the Console

Last updated: Jun-30-2025

Use the Cloudinary Console to define and manage roles that control access to features, settings, assets, and other types of content. Roles are reusable sets of permissions that you assign to users and groups to manage access within the Console, or to API keys to control what developers and applications can do via Cloudinary's APIs.

To view and manage roles, go to the Role Management page in Console Settings and select the Global Roles, Folder Roles, or Collection Roles tab.

Tip
You can also use the Permissions API to define custom roles and assign system or custom roles to a user, group, or API key.


Manage roles

You can:

  • View system roles
  • View create, update, and delete custom roles

The following sections explain how to handle roles of all different types.

View all roles

The Role Management page has a separate tab for Global, Folder, and Collection roles. Each tab shows a count at the top and filters tailored to the role type.

Tab Column Description
All Role Name Name of the role. Click to view details.
All Type Indicates whether the role is a System Role (predefined by Cloudinary) or a Custom Role (created by your organization).
All Description Optional explanation of the role’s purpose.
Global Roles Permission Level (scope) Whether the role applies at the account level or to product environments. (Folder and collection roles are always scoped to a single product environment.)
Folder & Collection Roles Status Whether the role is Visible or Hidden in the Media Library. Hidden roles stay active where already assigned but can't be newly applied via the Media Library.

Global role management:
Global role management

Folder role management:
Folder role management

Collection role management:
Collection role management


Perform actions on roles

You can manage global, folder, and collection roles from the corresponding tabs in the Role Management page.

Action Applies To Permission Type Description
View details All All View role name, description, and included permissions.
Edit Custom roles All Update the name, description, and permissions.
Create Custom roles All Define a new role from scratch or based on an existing role.
Duplicate All All Use any role as a template to create a new custom role.
Delete Custom roles All Remove roles that aren’t currently assigned.
Hide / Make Visible All Folder and collection Toggle visibility in the Media Library.

Note
You can’t edit system roles, but you can duplicate them to create custom versions.

View details, edit, and create roles

When creating or editing custom roles, or viewing system roles, you'll see similar fields across types.

All roles:

Field Description
Role name Name shown in the Console and when assigning the role.
Description Optional helper text to guide role assignment.
Copy from existing role Use an existing role as a template (available when creating new custom roles).
Permissions System policies included in the role. See System policies or use the Get system policies API.

Global roles only:

Field Description
ID Optional. If left blank, Cloudinary generates one automatically.
Permission level Whether the role applies at the account level or in a product environment.
Create global roles Create global roles Create folder roles Create folder roles

Assign roles

You can assign roles to groups, users, product environment API keys, and account API keys.

Tip
To automate role assignment or assign multiple roles at once use the Permissions API Guide.

Assignment considerations

You can assign roles to groups, users, product environment API keys, and account API keys.

All role types can be assigned 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 permissions list for details on which permissions are available by scope and applicable to each entity type.

Assign roles to users and groups

To fully manage role assignments for users, these are the key aspects to understand:

Grant product environment access to users

Selecting product environments when assigning roles only won't actually grant acctss to the product environment.

You need to grant product environment access to users directly by going to User Management > Users, clicking the edit icon in the Product Environments column, and selecting the product environments to assign.

Assign product environments

Assign roles to groups

Group roles allow all group members to inherit the same permissions, making it easier to manage teams with shared access needs.

Assign roles to new or existing groups from User Management > Groups by clicking + Create a Group or selecting Assign Roles from a group's context menu.

  1. Select a Permission level, either Account, All product environments, or a specific product environment.
    • If you select the system product environment Master Admin role, All product environments is selected and can't be changed.
    • If you select a system account-level role, Account is selected and can't be changed.
  2. Choose one or more roles to assign. Only roles relevant to the selected permission level are shown.

Important
Users inherit roles from their groups, including product environment–scoped roles. However, group membership doesn't grant access to those product environments. To give access, use the Product Environments column in User Management.

Group roles

Assign global roles to users

You can assign roles to users when inviting them, or by editing their profile later, both directly, and by adding users to groups.

New users

Grant permissions at the time of invitation by going to User Management > Users and clicking + Invite.

You can optionally assign the new user to one or more groups. The user will automatically inherit all roles assigned to those groups.

To assign roles directly:

  1. Select a Permission level, either Account, All product environments, or a specific product environment.
    • If you select specific product environments (or all), the user is granted access to them as part of this flow.
    • If you select the system product environment Master Admin role, All product environments is selected and can't be changed.
    • If you select a system account-level role, Account is selected and can't be changed.
  2. Choose one or more roles to assign. Only roles relevant to the selected permission level are shown.

Invite a new user

Existing users directly

To assign or edit roles for an existing user, go to User Management > Users and click Assign Roles from the user's context menu.

Choose the Permission level (either Account, All product environments, or a specific product environment), and assign one or more roles.

Assign roles to an existing user

Important
Selecting a product environment for existing users assigns roles within that environment, but doesn't grant the user access to it. To grant access, use the Product Environments column on the User Management page.

Existing users via group

Users inherit all roles from the groups they belong to. Managing user roles via groups streamlines permission granting because it allows you to add roles to multiple users at once. It also helps apply governance standards by controling permissions via groups of users.

To assign or edit roles for an existing user, go to User Management > Users and click Edit Details from the user's context menu. Select one or more groups.

Assign groups to an existing user

Assign content roles to users

Content roles apply to specific folders or collections. These roles can be assigned from the Media Library using the Share menu, or via the Permissions API.

Assign roles to API keys

Product environment API keys

You can assign product environment API keys roles that apply to their specific environment and support programmatic access. These roles can include global roles (e.g., transformations, upload presets) or folder-level roles (e.g., upload, download, rename, move). API keys are typically used with the Admin and Upload APIs to access media and metadata.

  • Assign global roles from Settings > API Keys.

  • Assign folder roles from the relevant folder in the Media Library. For more information, see Folder sharing and permissions.

Account API keys

Account API keys support only account-level global roles that can be used programmatically, such as user provisioning. These keys are primarily used for provisioning and Permissions API operations.

  • Assign account-level global roles from Settings > Account API Keys

Use cases

Give developers broad access to metadata and assets

A developer building internal tools or dashboards may need access across multiple folders. You can create a custom global role scoped to a product environment that grants:

  • View all assets
  • Manage tags and metadata
  • Access usage reports

Then assign the role to their API key via the Console or API Keys page.


Assign roles to match team structures

Map roles to internal groups like “Creative,” “Marketing,” or “Staging” for folder-specific access. For example:

  • Creative team: Full access to /Creative
  • Marketing: Read-only access to /Creative, full access to /Marketing

Steps:

  1. Create user groups in User Management
  2. Create custom folder roles
  3. Assign them via the Share button in the Media Library

Grant access for platform administration

DevOps or technical admins may need to manage users, groups, product environments, and security settings, without media access.

Create a global role scoped to the account, with permissions like:

  • Manage users and groups
  • Manage product environmens
  • Manage account security settings

Then assign it via User Management or the Permissions API.

✔️ Feedback sent!

Rate this page: