Assign roles

This guide describes the Roles and Permissions system. For details on all roles available in the legacy system, see Role-based permissions.

Overview

You can assign all roles defined in your account to principals, including users, groups, and API keys.

• Use the Permissions API to assign global, folder, and collection roles.

  For Free plan customers:

  The Permissions API isn't available on the Free plan. You can manage roles and permissions via the Console only and assign folder roles to API keys and other principals programmatically via the Admin API.

• Use the Admin API to assign folder roles.

Assign roles via the Permissions API

Enterprise customers can use their account management keys to manage and assign all roles via the Permissions API.

Base URL and authentication

All Permissions API endpoints on this page use the following base path:

Replace ACCOUNT_ID with your actual account ID.

Find your account ID and credentials in the Account Management Keys page of the Console Settings.

Method 1: Assign a role to multiple principals

Use this method when you want to assign the same role to multiple principals.

Endpoint:
PUT /permissions/roles/{role_id}/principals

The request body should include:

• An operation field (at the top level) that defines whether to add or remove the listed principals.
• A principals array containing one or more principal assignment objects.

Example 1: Assign principals to an account role

Example 2: Assign a global role across different product environments

Example 3: Assign a content role to different folders

Example 4: Remove a principal from a role

Method 2: Assign roles to a principal

Use this method to assign multiple roles of different permission types and scopes (account, product environment, global, and content) to a single principal:

PUT /permissions/principal_roles

The request body should include:

• An operation field (at the top level) that defines whether to add or remove the roles from the specified principal.
• A principal object specifying the principal to assign roles to.
• A roles array containing one or more role assignment objects. Each object may optionally include scope_id and/or policy_parameters, depending on the role.

Example: Assign multiple roles of different types to a principal

Inspecting role assignments

Use these endpoints to view current role assignments and permissions:

View effective permissions

Use the GET /principal_roles/inspect endpoint to check which roles or permission policies apply to a user, group, or key, based on specific content, product environments, or scopes.

This endpoint is especially useful for debugging access issues, such as:

• Why a user can or can't access a folder or collection

• Whether a key has permission to perform an action in a specific product environment

• Confirming inherited or global role assignments

You can filter by:

• Principal: principal_type and principal_id

• Scope: scope_type (account or prodenv), and scope_id if needed

• Content instance: folder_id, collection_id, or asset_id

To inspect broad access, you can also use special values like folder_id=all.

Assign folder roles via the Admin API

You can use the Admin API to assign folder roles to users, groups, and API keys. This provides an alternative method for folder role assignment alongside the Permissions API.

Base URL and authentication

You can assign roles to users, groups, and product environment API keys to grant permissions for specific folder instances via the Admin API.

By default, the Admin API endpoints use the following format:

https://api.cloudinary.com/v1_1/:cloud_name/:action

For example, to list all video assets in the cld-docs product environment:

The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret (which can be found on the API Keys page of your Cloudinary Console Settings) are used for the authentication.

You can experiment with returning a list of the images in your own Cloudinary product environment by replacing the API_KEY, API_SECRET, and CLOUD_NAME in the cURL command below:

folder_operations/invite

Enables you to grant or remove roles for a specific folder to a principal (user, group, or API key).

Get folder roles

Lists the principals and their roles assigned to a specific folder.

Syntax

GET /folder_operations/invite/:folder_external_id

Required parameters

Example

Get the roles assigned to a specific folder:

Sample response

Assign folder roles

Assigns or removes roles for a specific folder to a principal (user, group, or API key).

The operation supports system folder roles such as cld::role::content::folder::editor. For a full list of system folder roles, see Folder roles.

Enterprise customers can also create and assign custom roles via this endpoint using the custom role's ID. To learn more about custom roles, see Manage roles via API.

Syntax

POST /folder_operations/invite/:folder_external_id

Required parameters

Examples

Assign the folder manager role to an API key:

Assign the folder editor role to a user:

Sample response