Manage roles

Cloudinary roles define what users, groups, and API keys can access and do across your account. Managing roles via the Permissions API allows you to create, update, and delete custom roles programmatically—so you can scale permissions consistently without assigning individual policies one by one.

On this page, you’ll learn how to:

• Retrieve roles and policies
• Manage custom roles
• Considerations for planning roles effectively

Retrieve roles and policies

Use these endpoints to inspect and audit your roles and available policy options:

For more information on system roles and policies, see System roles and policies.

Manage custom roles

Use these endpoints to manage custom roles for your account or product environments.

Create a custom role

Use POST /roles/custom to define a role and include the system policies it should grant.

You must specify:

• permission_type: global or content
• scope_type: account or prodenv
• One or more system_policy_ids
• (Optional) id, name, and description

Global roles apply to all content or account-level features. Content roles apply to specific folders or collections and require policy_parameters when assigning.

Example 1: Create a global role to manage uploads

Example 2: Create a content role for folder access

Example 3: Create an account-level role for admin tasks

Update or delete a custom role

• Update a role: PUT /roles/custom/{role_key} You can update the role’s name, description, or system policies.

• Delete a role: DELETE /roles/custom/{role_key} Roles can only be deleted if they aren’t currently assigned.

Considerations for planning roles effectively

Actions that require multiple permissions

Some tasks require multiple permissions to enable. If a user doesn't have all the permissions listed for that action, they won't be able to perform it. Make sure the roles you create contain all the listed permissions to perform these actions: