Manage and assign roles

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.

Manage roles

You can:

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

All roles contain permissions (called system_policies in the API) that are pre-defined by Cloudinary. These permissions determine what the role allows.

• System roles include a fixed set of permissions. You can view them, but you can’t choose which ones to include.
• Custom roles let you choose which permissions to include.

Cloudinary provides system roles for that apply globally, as well as to folders and collections.

You can create custom roles that apply globally and to folders.

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

View all roles

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

Roles display in a table format. Here’s a summary of the columns shown:

Global role management:

Folder role management:

Collection role management:

View role permissions

In the main view, you can see each role's name, permission level (global roles), type, and description. However, to understand what a role actually allows, you'll need to view the specific permissions that the role contains.

To do this, select View (for system roles) or Edit (for custom roles) from the (3-dots) options menu.

• The role details panel lists all available permissions relevant to that role type, with the assigned permissions checked. These permissions define what users with the role are allowed to do.

• Each permission has a tooltip that gives more details:

  • Hover over the i icon to see a description of what the permission enables.
  • Developers can hover over the tree icon to view the underlying system policy statement, which specifies the exact resources, features, and actions the permission grants access to.

Create custom roles

When creating custom roles, you can customize the same attributes you see when viewing roles.

When creating a new custom role, you define the Role name and Description. Additional options include:

• ID: The unique identifier for this role. You can enter a custom ID that follows your company’s naming conventions, or leave it blank to have one auto-generated.
• Copy from existing role (global roles only): Use an existing role as a template.
• Permission level (global roles only): Specify whether the role applies at the account level or in product environments.
• Permissions: Select the system policies to include in the role. These determine what users with the role are allowed to do.

Create global roles Create folder roles

Permission levels and available permissions

All roles have a permission level, which determines the scope where the role applies and which permissions are available to assign.

• For global roles, you choose whether the role applies at the account level or at the product environment level when creating or assigning the role. The available permissions differ based on this selection, and you can only assign roles that match the selected level.

• Folder (and collection) roles are always scoped to a product environment. You assign these roles from within specific content instances that are inherently tied to a product environment.

The role creation form dynamically filters permissions based on your selection. You can see a full reference of all available system permission policies.

Edit custom roles

Whereas you can only view system roles, you can also edit custom roles of all types. When you click Edit from the (3-dots) options menu, you can change a custom role's name, description, and the permissions it contains. However, you can't change the permission level for a global role that already exists.

Assign roles

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

Assign roles to users and groups

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

• How to grant product environment access to users
• How to assign roles to groups
• How to assign global roles to users (including new and existing users, directly and via group membership)
• How to assign content (folder and collection) roles to users

Grant product environment access to users

Selecting product environments when assigning roles only won't actually grant access 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 roles to groups

Group roles allow all group members to inherit the same permissions, making it easier to manage teams with the same 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.

Assign global roles to users

You can assign roles to users when inviting them into an account, or by editing their profile later, either directly or 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.

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.

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 controlling permissions via groups of users.

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

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.

• Folder sharing and permissions
• Collection sharing and permissions

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

Product environment API keys are commonly used with the Upload and Admin APIs, as well as other Cloudinary APIs such as the Analyze API and Live Streaming API, to manage media, metadata, and related product environment entities.

• Assign global roles from the (3-dots) options mention for a key in Settings > API Keys.

  

• You can assign folder roles to API keys programmatically via the Permissions API.

Account API keys

Account API keys support only account-level global roles that can be applied programmatically via the Provisioning and Permissions APIs, such as user provisioning, role management, API key management, and product environment creation.

• Assign account-level global roles from the (3-dots) options mention for a key in Settings > Account API Keys.

SAML SSO

You can assign Cloudinary roles using SAML SSO by following the steps in our SAML SSO documentation.

However, if you're assigning the granular roles described in this guide (those that use Cloudinary role IDs), there’s a slight change to the setup.

To assign these roles, provide:

• An array of product environments the user should access via CloudinarySubAccounts, as in the usual setup.

• An array of roles to assign (via the CloudinaryRole field), using the following syntax:

  Note

  Use these fields in Okta or the equivalent fields in your identity provider.
  • <cloud_name>::<role_id>

    For example:

    my-org-production::cld::role::prodenv::admin assigns the Admin role to the product environment with cloud name my-org-production.

  • *::<role_id>

    For example:

    *::cld::role::prodenv::ml_user assigns the Media Library User role to all product environments.

  • ACCOUNT::<role_id>

    For example:

    ACCOUNT::cld::role::account::billing assigns the Billing role at the account level.

Tips and considerations

• You can assign up to 30 product environments, or assign the user to all product environments.

• You can assign up to 10 roles at a time.

• Make sure the product environments listed in CloudinaryRole match those provisioned via CloudinarySubAccounts. If they don’t match, the user is granted access to all product environments.

• If you don't specify a role, the media_library_user role is assigned by default.

  If you don't specify product environments, the user is assigned to all by default.

• SAML SSO supports Cloudinary's legacy roles and permissions for backwards compatibility.

  If you provide a legacy role name (e.g.,tech_admin), that role is assigned to the account for all provisioned product environments, or to all product environments if none are provisioned.

Considerations for planning roles effectively

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 principals. However, some assignments may have no practical effect, depending on permission level (scope) or usage context:

• Permission-level matters: Assigning an account-level role to a product environment API key has no effect.

  For example, granting a product environment API key permission to provision users via the Provisioning API won’t work. Those permissions are only relevant at the account level.

• UI-based permissions: Roles that grant access to UI areas, such as viewing dashboards or reports, don’t apply to API keys, since only users (not API keys) can interact with the Console.

  Exception: If you’re using an API key to authenticate an integration that embeds the Media Library Widget, you must assign a role that grants access to the Media Library. For more information, see Integrations.

See the full list of system permission policies for details on which permissions are available by scope and applicable to each entity type.

Integrations

You connect to your Cloudinary integrations using a product environment API key. For the integration to work correctly, you must assign the key access the Cloudinary functionality it requires, such as accessing the Media Library, viewing folders, or adding assets to collections.

When setting roles and permissions for API keys used to access integrations:

• Avoid giving broad roles like Master Admin to an integration’s API key. It opens more access than what the integration likely needs.

• Instead, understand what the integration needs to do. Then assign an appropriate role.

• For integrations that use the Media Library Widget, the API key needs specific permissions to access content. Consider one of the following options:

  • Global roles
    • System roles: Use a role like Media Library User or Media Library Admin, if it matches the required access level.
    • Custom roles: Assign a custom global role that includes the Access the Media Library permission as well as global folder permissions (e.g., view, upload, delete).
  • Content roles
    • Assign system or custom folder or collection roles for targeted access to specific instances.
      Notes

      • When assigning content roles, you must also assign a global role that grants the Access the Media Library permission
      • You can only assign content roles to API keys programmatically. For more information, see Assign roles.

Multiple permissions

In some cases, doing a single task, like moving an asset or creating a collection, requires more than one permission. If the user or API key doesn’t have all the required permissions, they won’t be able to complete the task.

For example:

To avoid frustration, double-check that the roles you assign include all the permissions needed for the actions your team or tools are expected to perform.

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 an API key, using either the Console or API Keys page, and provide the key to the developer for use in their application.

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.