Migrating to Roles and Permissions

What to expect

Cloudinary is rolling out a modern, unified Roles and Permissions system designed to provide enterprise-grade access control, structured collaboration, secure automation, and safe AI-driven workflows.

Here's what the migration means for you:

• Zero downtime and zero action required: The migration is fully managed by Cloudinary and requires no downtime or asset reprocessing.
• Continuity of access: All existing permissions are preserved. Any user who could previously view assets, perform actions, or manage folders will continue to do so. Existing roles are automatically mapped to the new system using predefined mappings.
• No rollback: The legacy permissions model is fully retired after migration. Migrated accounts cannot revert to the old system.

What's new

After migration, you'll notice a brand-new, centralized UI for managing roles and permissions:

• Centralized Role Management page: Instead of permissions being scattered across different areas, there is now one unified place in the Console to manage roles and assignments across the entire platform.
• Redesigned invite and assignment modals: The modals for inviting users, managing groups, and configuring API keys have been completely redesigned. When inviting users, you can assign them to groups, apply an access bundle for quick setup, or assign roles directly:

Assign to groups Apply an access bundle Assign roles directly

• Multiple roles per user, group, or API key: You're no longer restricted to a single role per principal. The new system is aggregative — access is determined by the union of all assigned roles.

Key structural changes

While your existing access is preserved, the underlying model has been upgraded for much more flexibility:

• Account vs. product environment roles: In the past, roles applied globally across your entire account. Now, roles are split. You can assign account-level roles (such as Account Master Admin, Account Admin, Account Billing) and product environment-level roles (such as Master Admin, ML Admin, Moderator) separately.
• Different roles per environment: You can now assign different roles to the same user across different product environments. For example, a user can be an Admin in your Staging environment but only have Viewer access in your Production environment.
• Global roles for user groups: Previously, groups could only carry folder and collection access permissions, with the primary role assigned to each member individually. Now you can assign the primary role in the form of global roles (account-level and product environment-level) directly to a group, and all members inherit those roles automatically.
• Consistent UI and API enforcement: Permissions are now consistently enforced across the Cloudinary Console and APIs, ensuring backend-level access control.

Changes to user, folder, and collection management

Folder roles

Previously, folder-level access was restricted to users with the Media Library User role. In the new system, content roles (Viewer, Contributor, Editor, Manager) can be used much more flexibly by different users.

If you're used to sharing folders, the modal looks and feels mostly the same, but there's an additional folder role called Distributor, which grants permission to manage public links.

Media Library permissions as standalone roles

Specific Media Library capabilities that used to be toggles inside the user invite modal — such as Show delivery URL, Create collection, and Create proof — are now standalone global roles (Delivery URL Viewer, Collection Creator, Proof Manager). Because they are independent roles, they can be assigned to anyone in the system.

Collection roles

The existing collection permission levels (Can view, Can share, Can collaborate, Can manage) have been unified into the central role-based access control infrastructure as predefined content roles.

Changes to API and account management keys

To improve security and support safe automation, both product environment API keys and account management keys (formerly provisioning API keys, and account API keys, Enterprise only) are now fully integrated into the role-based access control system. New keys of either type are created with no default permissions. You must explicitly assign a role for them to work.

Existing keys are automatically migrated to preserve current access:

• Product environment API keys: Migrated to the product environment Master Admin role.
• Account management keys: Migrated to the account Master Admin role.

Feature availability by plan

While the unified permissions foundation applies to everyone, advanced capabilities depend on your plan:

• Free and self-serve plans: Includes the new unified infrastructure, the new UI, role assignments across product environments, role assignments to API keys, multiple roles per user or group, and out-of-the-box global and content predefined roles.
• Enterprise plans: Unlocks granular action-level role configuration. You can create custom global roles and grant granular API key permissions based on specific allowed actions. Also unlocks the new Permissions API for automated, programmatic management of roles and groups at scale.
• Assets Advanced plans: Unlocks granular folder-level and content-level role configuration. You can customize content roles by defining exactly which actions are allowed on specific folders or collections, and restrict API keys to specific folders.

Role mapping reference

The following tables show exactly how your existing roles, permissions, and API keys are automatically translated into the new system during migration.

Global user roles

In the legacy system, roles were applied globally. They are now split between account and product environment contexts.

Media Library permissions (standalone roles)

Previously, these were hidden toggles inside the user invitation modal under the Media Library User role. They are now explicitly assigned as standalone roles at the product environment level.

Folder roles

Legacy folder permissions map directly to the new folder roles.

Collection roles

Legacy collection permissions map directly to new collection roles.

Product environment API keys and account management keys

To ensure integrations continue running without interruption, existing keys are assigned the highest environment-appropriate role.