System roles and permission policies

Cloudinary provides predefined system policies and system roles to help you manage access to features, assets, and operations across your account.

• System roles: Built-in roles provided by Cloudinary. They're ready as-is to assign directly to users, groups, or API keys. Browse the list of available system roles and which permissions they grant.

• System policies: Predefined permission policies offered by Cloudinary. These are the building-blocks of all roles. Browse the list of system policies so that you can know which policies to use when building your custom roles.

System roles

Use this section to browse all system roles provided by Cloudinary and see which permissions each one grants.

You can use this list to:

• Decide which role to assign to a user, group, or API key
• Review the permissions granted by roles that are already in use

List all system roles

To retrieve all available system roles, use the GET /roles endpoint with the management_type=system filter.

The response includes metadata for each role:

Field definitions:

Field	Description
id	The API role key used when assigning roles programmatically. System roles use the cld::role:: prefix.
name	Display name for the role, as shown in the Console.
description	Summary of the access level the role grants.
management_type	Always "system" for predefined roles.
permission_type	Indicates the level at which the role applies — usually global.
scope_type	Specifies the scope of the role. For system roles, this is often "account", meaning the role applies at the account level.
created_at, updated_at	Timestamps indicating when the role was created and last updated (Unix epoch format).

Get details for a specific role

To see the exact permissions a role provides, use the Get roles/{role_id} endpoint.

This returns all the system policies included in the role, along with their policy_statement values:

Use this to audit or evaluate what a role allows before assigning it.

System policies

System policies define specific capabilities, such as uploading assets, managing collections, or updating metadata. These are the foundational building blocks for all roles in Cloudinary.

Use this section to:

• Understand what system policies are and how they work
• Browse available policies and descriptions to decide which to include in a custom role
• Reference policy IDs when creating custom roles via the API or Console

Key characteristics

• Task-specific: Each policy grants a specific permission, such as creating collections or updating assets.
• Predefined and immutable: All system policies are defined by Cloudinary in the Cedar policy language. You can reference them but not modify their logic.
• Reusable in roles: System and custom roles are both composed of system policies. System roles include a predefined set; custom roles include the policies you choose.
• Assigned through roles: When you assign a role to a user, group, or API key, Cloudinary automatically applies the system policies included in that role.

Referencing policies in custom roles

When creating a custom role, include one or more system_policy_id values to specify what that role allows.

Example: Create a custom role using system policies

List all system policies

To retrieve a full list of system policies available to your account, use the GET policies/system endpoint.

Example: System policy API response

Field definitions:

Field	Description
id	The unique system_policy_id used when referencing this policy in roles.
name	The display name of the policy, shown in the Console.
description	A summary of what the policy allows, including relevant UI and API capabilities.
scope_type	Defines the scope at which the policy applies. Typically "prodenv" for product environments.
permission_type	Indicates whether the policy applies globally or in a more granular context (e.g., "global").
policy_statement	The underlying Cedar policy expression that defines the permission logic.
created_at, updated_at	Unix timestamps indicating when the policy was created and last updated.