Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

Image & Video APIs
Menu

Assign roles

Last updated: Nov-05-2026

Note
This guide describes the Roles and Permissions system. A small number of accounts still use the legacy permissions system. If your account is one of them (there's no Role Management page in your Console Settings), see Legacy permissions.

Overview

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

Plan availability:
The Permissions API is available on Enterprise plans only. It isn't available on the Free plan or on self-serve paid plans. Creating custom roles is also Enterprise only, whether you do it in the Console or via the Permissions API.

On the Free plan and on self-serve paid plans, you can:

Tip
To learn how to provision roles using SAML SSO, see SAML SSO.

On this page:

Assign roles via the Permissions API

Use an account management key, a credential available on Enterprise plans only, to manage and assign all roles via the Permissions API.

Each role assignment requires the role's id:

Permissions the key needs to assign or update roles
An account management key can only assign a global role if the key's own roles already include all the permissions in that role, at the level you're assigning it. The check compares permissions, not roles. The key's permissions can come from several of its roles, and you can assign them in roles that group them differently.
  • Account role: The key's account roles must include all the permissions in the roles it's assigning.
  • Product environment role, with a scope_id: The key needs all the role's permissions in the product environment you specify. They can come from roles assigned to the key for that product environment, from roles assigned to it for all product environments, or both. Permissions the key has only in a different product environment don't let it assign the role there.
  • Product environment role, without a scope_id: When you omit scope_id in PUT /roles/{role_id}/principals or PUT /principal_roles, you assign the role for all product environments. The key needs all the role's permissions from roles that were also assigned to it without a scope_id. Having the permissions in each product environment separately isn't enough, even if the key has them in every one.
  • Update to an assigned role: When you update a global role that's already assigned and your request includes system_policy_ids, the key needs all the permissions in the updated role, not only the ones you're adding or removing. For a product environment role, the key needs those permissions from roles assigned to it without a scope_id. Updates to roles that aren't assigned to any principal aren't checked.

Permissions the key gets from custom policies don't count. If a role in the request includes permissions the key doesn't have, the API returns a 403 error that lists those roles and makes none of the requested changes to role assignments or system policies. Removing roles isn't checked. Folder and collection roles aren't part of this check, because sharing controls access to specific folders and collections.

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.
Field Applies To Description
operation Top-level Whether to add or remove the listed principals from the role.
Values: add, remove
Principal object fields: (Each object in the principals array must include the following fields.)
principal_type Each role assignment Type of principal.
Values: user, group, apiKey, provisioningKey
principal_id Each role assignment Unique ID of the user, group, or key receiving the role.
scope_id Each role assignment (if scoped to a product environment) The product environment ID. Find this on the Product Environments page.
policy_parameters Each role assignment (if the role applies to a specific folder or collection) ID of the folder or collection the permission applies to.

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.
Field Applies To Description
operation Top-level Whether to add or remove the listed roles from the principal.
Values: add, remove
Principal object fields: (The principal object must include the following fields.)
principal_type The principal Type of principal.
Values: user, group, apiKey, provisioningKey
principal_id The principal Unique ID of the user, group, or key receiving the role.
Role object fields: (Each object in the roles array must include the following fields.)
id Each role ID of the role to apply to the principal.
scope_id Each role assignment (if scoped to a product environment) The product environment ID. Find this on the Product Environments page.
policy_parameters Each role assignment (if the role applies to a specific folder or collection) ID of the folder or collection the permission applies to.

Example: Assign multiple roles of different types to a principal

Inspecting role assignments

Use these endpoints to view current role assignments and permissions:

Endpoint Use Case
GET /roles/{role_id}/principals See who has a specific role.
GET /principal_roles See what roles a user or key has.
GET /principal_roles/inspect View effective permissions for a user or key (debug access issues).

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.

Tip
See the GET /principal_roles/inspect for specific code examples.

Assign folder roles via the Admin API

You can use the Admin API to assign folder roles to users, groups, and API keys. For full details, see folder_operations in the Admin API.

The folder_operations endpoint provides an alternative way to assign folder roles alongside the Permissions API.

You currently can't assign folder roles to API keys in the Console, so the only way to do so is programmatically.

If you don't have an Enterprise plan:
The folder_operations endpoint is your only programmatic option here. The Permissions API isn't available on the Free plan or on self-serve paid plans, so use this endpoint to assign folder roles to API keys.

For other role management tasks, see:

See also

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars