Define custom policies

Cloudinary custom policies let you define fine-grained API-level permissions using Cedar-based policy statements. These policies allow precise control over what API keys can do, including folder-level access, asset operations, metadata updates, and upload configurations.

Use custom policies to grant secure, automated access to developers building AI workflows, integrating with CI/CD pipelines, or working in specialized product environments. Cloudinary provides a Cedar schema and a Permissions API to help you enforce policy as code at scale.

This guide contains the following sections:

• Custom policies overview: Explains how to create and manage API key permissions using custom policies.
• Policy statement overview: Describes the components of a policy statement and includes the Cloudinary-defined Cedar schema, which details the valid resources, actions, and principals you can use in your policy statements.
• Notes and considerations: Covers important details and considerations when implementing custom policies.
• Use cases and examples: Presents various scenarios and examples to demonstrate practical applications of custom policies and how they can be effectively utilized. It includes sample Admin and Upload API calls and responses to illustrate the impact of custom policies.

Custom policies overview

By default, all actions on all resources are forbidden for all principals. Consider which developers within your organization have common permission needs, and create corresponding API keys from the API Keys page of the Console Settings.

After creating your API keys, use the Create custom policies endpoint to grant specific actions to each API key and assign them to the appropriate developers. Any actions not specified in your policies will remain prohibited.

Custom policies include the following attributes:

• scope_type: Specifies the level that the permissions apply to. Currently, the only available option is prodenv (product environment).
• scope_id: Specifies the ID of the product environment that you want the permission to apply to. You can find the product IDs for all your product environments on the Product Environments page of the Console Settings. Make sure you're copying the ID for the correct product environment and that it corresponds with the API keys you're trying to set permissions for.
• policy_statement: The Cedar statement that specifies the permissions. You can use any valid combination of actions, and resources in your Cedar policy statement to grant permissions for API keys relevant to your organization.

If your custom policy applies to a specific folder or asset, you'll need to specify the folder's external ID within the policy_statement. Find the folder's external ID using the Get root folders or Get subfolders method.

Policy statement overview

The policy_statement, written in Cedar language, is required when creating and updating custom policies using the Permissions API. This statement defines who can or cannot perform specific actions on designated entities.

Here's an example of a policy_statement that allows the API key 1234 to read all assets in the Clothing folder:

Not specifying a particular principal, action or resource will result in automatically allowing permissions to all instances of the unspecified entity. For example, permit(principal, action, resource) allows all actions on all resources for all principals.

Here's a summary of the principals and resource types that can receive permissions for each action:

Here's a summary of the filters (when statement in the policy_statement) that can by applied to each entityType:

Cedar schema

The Cedar schema is predefined and provided by Cloudinary, detailing the valid parameters within the policy_statement. The Cedar schema corresponds to the elements of the policy_statement:

Here's the Cedar schema:

Notes and considerations

Review the following sections for key information on managing your custom policies.

Permit and forbid policy statements

A Cedar policy statement allows you to either permit or forbid a certain action. Forbid statements always take precedence over permit statements. For example, if an action on a particular folder is forbidden for a principal, you can't permit that action on an asset or subfolder within that folder for the same principal.

It's important to review your custom policies to verify the permissions granted to each API key and ensure there are no policy conflicts. Use the Get custom policies endpoint to retrieve all enabled policies for a specific scope_id.

Permissions API scope and limitations

The Permissions API is currently enabled for specific product environments only. You can't create policies for product environments where the API isn't enabled.

Additionally, you can't set permissions for the Assets product via the Permissions API. Policies can only be configured with an API key as the principal; the user principal is not valid. Permissions for all areas of the Console, including Assets, Settings and other products, are set via the User Management page of the Console Settings. When assigning user permissions to the Console, keep in mind that Master admin, Admin or Technical admin user roles have access to all API keys. For more information, see Role-based permissions.

Critical default policy

Cloudinary provides the permission prodenv allow DAM custom policy to allow full use of the Console. Ensure this policy isn't deleted, as its removal will block Console access for all users.

API permissions setup method

By default, all API actions on all resources are forbidden for all principals. To set up API permissions, explicitly grant specific actions to individual API keys. Any actions not specified in your policies will remain prohibited. Consider which developers within your organization have common permission needs, and create corresponding API keys from the API Keys page of the Console Settings.

For more details about administering permissions, see Permissions API requests.

Behavior of forbidden actions in API calls

Behavior for informing the user that an attempted action was forbidden may vary in different API calls.Some calls will return a 403 error, while others—especially those involving a mix of permitted and forbidden actions—will return a 200 status with detailed responses. Here are some examples:

Example 1: Update metadata

When attempting to add metadata to several assets using the metadata endpoint of the Upload API, the response may return a 200 status and include an object specifying which assets were successfully updated and which were unauthorized:

Example 2: Get subfolders

For the Get subfolders endpoint, if the request is forbidden, the response will indicate this:

Example 4: Get root folders

For the Get root folders endpoint, forbidden folders won't appear in the response, while the total_count will reflect the total number of folders in the product environment:

Use cases and examples

Below are example configurations for different scenarios and use cases:

Setup for product detail page (PDP) developers

Suppose the developers working on your e-commerce website's product detail pages (PDP) need full access to product-related assets only. Use the Create custom policy endpoint to set up the following permissions for the API key you'll give those developers:

• Forbid access to non-product assets in the dedicated Non-product folder. (Access is prohibited by default, so no additional permissions need to be set.)

• Allow full management of the Product folder, including permission to retrieve information about it, create (upload assets to it), update, and delete it, as well as move assets and subfolders from the Product folder.

• Allow read access to structured metadata, meaning, the ability to retrieve information about all structured metadata fields and their attributes.

Allow full management access over the Product folder

Sample response:

Allow read access to structured metadata

Sample response:

Sample responses for permitted and forbidden API calls

Setup for configuration administrators

Suppose some developers are in charge of system configuration, such as metadata and upload presets. Use the Create custom policy endpoint to set up the following permissions for the API key you'll give those developers:

• Forbid access to all assets and folders. (Access is prohibited by default, so no additional permissions need to be set.)

• Allow full management of structured metadata fields, including permission to read (retrieve information about them), create, update, and delete them.

Allow full management of structured metadata fields

Sample response:

Sample responses for permitted and forbidden API calls