Media Library administration

If you are a Master Admin or Admin user for your Cloudinary account, it may be your responsibility to manage account users, preferences and settings, and to monitor account usage.

This includes adding users, updating user configurations and roles, defining Media Library user groups, and viewing or setting Media Library and overall account preferences, and viewing usage statistics, graphs, and other reports.

Every user who accesses the Media Library requires a separate seat license.

User and group management

There are many types of users who are a part of any Digital Asset Management workflow. When you define users in Cloudinary, you assign a role to each user. These roles control the areas of the Cloudinary console that a user can access or modify.

A large majority of your creative team will probably work primarily in the Media Library. Thus, when you assign a user to the Media Library user role, you can define another level of permissions within the Media Library by assigning Media Library users to one or more user groups.

Within the Media Library, users can share folders and collections with selected user groups or individual users at varying levels of access permissions, from full management control to view-only access.

User group configuration

If you plan to create users with the Media Library user role, then it's recommended to first create all the user groups you expect to work with. For example, if you have different teams working on different product lines, you may want to ensure that only users from a particular product line can access folders related to those products or you may want to create a variety of dynamic collections to make it easy for relevant groups to find and view assets relevant to their tasks.

  • User groups can be assigned one of several access permission levels for each of the folders in your Media Library, and can separately be given varying permissions to work with each of the available collections. Consider the way you expect to sort your assets in folders and collections, and the different types of users who may be accessing those folders and collections, to determine the groups you will need. For full details, see Folders and Collections.
  • A user can belong to more than one group. In that case, if the permissions conflict between two groups, or between those for a group and those assigned to a specific user, then the higher level (less strict) permission will be applied.
  • You create and edit user groups in the Users tab of the account settings. You can also see the number of members in each group.


It's recommended to create all required user groups and then set up folder and collection sharing for these user groups before creating new Media Library users and assigning them to groups.

Keep in mind that if you do create a new Media Library user and assign them to a new group before any folders or collections have been shared directly with them or with the groups they belong to, that user will get an email notification about their new account and may log into Cloudinary before they have permission to view any content. In this case, the Media Library will appear completely empty for them.

User configuration

You can define and update account users in one of the following ways:

For each user, you can set:

  • First and Last name: The user sees their name below your cloud name when they log into the console.
  • E-mail: After creating a new user, that user will receive an email to this address to confirm their account. This email address is also used for logging in to Cloudinary.
  • Role: Controls which areas the user can access and which operations they can perform in those areas. For details, see Role-based permissions below.
  • Sub-account access: If your account includes one or more sub-accounts, you can define which sub-accounts each user can access. Users with the Master admin role always get full control in all sub-accounts. Therefore, this option is displayed only when you select a role other than master admin. By default, users are given access (at the same role level) to all sub-accounts. Clear the check box to select which sub-accounts (if any) the user should have access to.
  • User Groups: User groups are relevant only for users with the Media Library user role, so this option is displayed only when a Media Library user is selected. This section displays all User Groups that have already been defined. For details, see Group configuration.
  • User Permissions: User permissions are relevant only for users with the Media Library user role, so this option is displayed only when a Media Library user is selected. This section includes permissions for creating and sharing collections. Without these permissions, a Media Library user can still view or contribute to collections shared with them, but without these permissions selected, they cannot create or share collections, even if they are assigned Owner level permissions for a collection. Note that users with Share collection permission can share collections both internally and externally.

Regardless of which method you use to define the users in your account, you can optionally enable SAML login, as described in User settings below.

Role-based permissions

Each user in your Cloudinary account is assigned a role. This role defines the operations a user can perform on your account, the areas of the Cloudinary console that they can view or change, and the settings they can control.

Below is a table summarizing the permission details for each role:

Table summarizing all role-based permissions


  • If you do not add a Media Library user to any groups and/or if no folders are shared with those groups or directly with that user, the user will not see any content in the Media Library.
  • The Media Library user role replaces the now obsolete 'Contributor' and 'Viewer' roles. For users who were assigned these roles, Cloudinary has made the following adjustments to ensure that the access permissions these users previously had remained unchanged:
    • Users in either of these roles have been automatically migrated to the Media Library user role.
    • Viewer and Contributor user groups were automatically created for your account and these users were added to the relevant group.
    • The Home folder has been shared with these two user groups at the corresponding level (Can view or Can contribute). For more details, see Folder sharing and permissions.

Media Library preferences

Media Library preferences enable you to control the behavior and/or appearance of the Media Library, such as determining the way custom metadata is displayed and maintained or what is included in the results when you run an Advanced Search.


  • The Media Library Preferences pane is available only for users with a master admin role. Changes to these options apply for all users in the account.
  • Most of the options in the Media Library Preferences pane impact only the Media Library experience. However, the Keep existing metadata when uploading newer versions of an asset option impacts both Media Library uploads and the Cloudinary Upload API. Therefore, if your organization also uses the Cloudinary Upload API, make sure that all relevant developers are in sync on the settings of this option, as changes to it could impact applications in production.

To access the Media Library preferences, select Preferences from the Media Library navigation pane.

Media Library preferences

After you modify and save modifications to the Media Library preferences, logged in account users may need to refresh their browsers to apply the changes.

Account settings

In addition to defining Media Library preferences, you can configure additional settings that influence how your account's media is uploaded, stored, and delivered. These account settings can affect both DAM users and developers who work with your Cloudinary account. Click the Settings icon at the top-right of the console to view your account settings.

Account settings

The User and group management settings already covered on this page are managed in the Users tab of the account settings. The following sections highlight a few additional settings that are specifically relevant to Digital Asset Management activities.

However, each organization should review all the available options in all tabs of the account settings and determine the settings that best answer your organization's needs.

Upload settings

The Upload tab of the account settings includes options that impact the default behavior applied to media when you upload it to your account. Those you may want to pay special attention to include:

Automatic backup: Determines whether every uploaded file is securely backed up, including support for multiple revisions. When enabled, the backups increase your account's storage usage.

Media Library upload presets: Upload Presets are a predefined set of upload preferences. Common settings you can define in an upload preset include:

  • Whether the public ID of uploaded assets will include random characters or will exactly match the uploaded filename.
  • Whether to allow overwriting of existing assets.
  • Which add-ons (if any) will run on each uploaded asset, such as auto-tagging or automatic moderation add-ons.

To control the way all assets are uploaded via the Media Library, you can assign specific signed upload presets to act as the defaults for image, video, and raw uploads within the Media Library.

Default upload preset settings

The relevant default upload preset will then be applied to every asset of that type that is uploaded via the Media Library UI from that point forward, unless a different signed preset is manually selected via the Media Library Upload Widget.

For more details on upload presets, see Upload presets.

User settings

The Users tab of the account settings includes your personal user profile details and email preferences. If you are an account administrator, this tab also includes settings that impact all account users as well as the option to add or modify individual users and permissions. The following may be useful for DAM account administration:

SAML login: This option enables the Cloudinary account administrator to activate SSO login. This can enable users in your organization to login using the same authentication system that you use for other SSO-supported applications. If you activate this option, you can globally select whether to Enforce SAML login or to allow users to potentially log in either via the SSO application or directly log in to the Cloudinary console. If you choose the latter ('Enforce' is disabled), then when creating new users, you can optionally select Send invitation email for that user. When selected, that user receives an email inviting them to create a console password.


  • If you also use the SAML Provisioning feature, make sure the Two factor authentication user setting (2FA) is Disabled. You can configure two-factor authentication through your IdP, if required.
  • The Two factor authentication (2FA) user setting is ignored when using SSO to log in to Cloudinary, as the SSO iDP is trusted.
  • Even if you set Enforce SAML login to Enabled, any user created with the Master Admin role will automatically get an invitation to set a console password and will be able to log in directly to the console, if needed.

List of users: Enables viewing and managing all account users, including adding users, removing users, changing their roles, and more. This list is visible only to users with a Master admin or Admin role.

Structured metadata management

Structured metadata fields are a set of custom fields that you can define at the cloud level. The defined fields are added to all assets in your Media Library. For example, you could create custom fields for Product category, Status, Product ID, Rights expiration date (for copyrighted materials), Photographer, etc. Each organization can decide on the fields that are most appropriate for their needs.

Once these fields are defined by an account administrator, all DAM users (with relevant permissions) can then set values for these fields on individual assets. This enables better searchability of your assets as well as opening up a variety of options for programmatic operations that your developers can perform based on the metadata values.

For each field you define, you can specify a field name, value type (string, number, date, list, etc), and other optional settings, such as range validation limits, whether the field is required, a default value that will be automatically set for that field for new assets, and a custom ID value for developers to reference when managing metadata fields programmatically.

Structured metadata field creation

Adding structured metadata fields

  1. From the Media Library Preferences, click Manage Structured Metadata to open the Manage Structured Metadata page.
  2. Click Create a new field and then define the field Label (display name) and Field type.

    If programmers in your organization sometimes manage structured metadata fields programmatically, you may also want to select the Customize external ID checkbox and set a custom value. For more details, see the Considerations section below.

  3. Fill in the relevant options for the field type you chose:
    • For string, number, and date fields, you can optionally set minimum and/or maximum values, a default value for new assets, and whether or not the field should be marked as a required field.
    • For single-selection or multiple-selection lists, first add the values you want to make available for your list. Afterwards, you can optionally select one of the defined values as the default field and whether or not the field should be marked as a required field. Each new value is added to the end of the list, but you can drag it to the desired location (or use the Move to top/Move to bottom buttons). Up to 3000 values can be defined for a list.

Structured metadata field considerations

  • When you create a new field, that field is immediately available from every asset in the Media Library.
  • If you choose to set custom external IDs for use with programmatic handling of structured metadata:
    • It's recommended to determine a standard naming convention for these together with the relevant developers.
    • If left blank, a random value will be automatically generated for the ID.
    • Once set, the field's external ID cannot be modified.
    • After the field has been created, the field's external ID (whether automatically generated or customized) is displayed in the field details pane, and can easily be copied and sent to developers as needed.
  • When you define a default value for a field, any assets added to your Media Library after the default value was defined will get that value. The field value will not be set for assets that were added previously.
  • A list field must, by definition, have at least one value. Therefore, when you create a new list field, it is automatically populated with an initial 'dummy' value. Edit this value to be the first value in your list, and then add additional values as needed.
  • To set a field as required, you must first set a default value so that new assets will already have a value for the required field.

    Once a required field has a value (either the default value or one that was set manually), users can modify the value, but they cannot remove the value and leave the field blank. For assets that existed in the Media Library before you set a field as required, the field will initially remain untouched. However, if a user clicks in a required field and then exits it without setting a value, they are notified that the field is mandatory.

    If you set a field as required, but don't want to apply any specific value to all new assets, create a default value such as "Empty" or "Select a value" or similar. Besides inviting users to update the value, it can be useful to search by this value to see which assets still require a value or to search for that value alongside other criteria and then perform a bulk update of the required metadata field for all assets that meet the defined criteria.

Managing existing structured metadata fields

After you create metadata fields, you can modify the field definitions, change the display order of fields or list values, block selected list values, or permanently remove a field.


  • Renaming a field takes effect immediately for all assets in the Media Library. You can also add additional values or modify value names for a single or multiple selection list, and these changes will take place immediately for all assets.
  • If you modify the value name (display text) of an existing list value, this change will also impact assets where the previous name was selected. Thus you should change existing list values only to fix spelling or make the value more clear for users, but you should not change the significance of the value once it's in use. If you want to make a completely different option available, add it as a new value.
  • If you no longer want a value to be available for selection, you can block the value. This removes the value from the selection options in the list for all assets, but does not delete or modify the value for any assets where that value is currently selected.
  • Even after a list item is blocked, you can still search for assets with that value in the Advanced Search. This can be useful to find all assets that used a value you've blocked to change them to other values.
  • Other changes to the definition of a field, such as adding, removing, or modifying default values, changing validation rules, changing the required setting, etc, impact new assets added to the Media Library after the change. Existing assets are affected by these changes only if a user chooses to edit that field.
  • You can also permanently delete an entire field. When you delete a field, the values that were set for that field in existing assets are also permanently removed.

Modifying field definitions and values programmatically

In addition to creating, updating, or deleting fields, or setting field values in the console, structured metadata fields and values can also be created, updated, or removed programmatically by developers in your organization using Admin and Upload API methods.

For example:

  • Add a very long list of possible values to a field, where the values are pulled from external data, such as a list of cities or countries, a set of product codes, a list of suppliers, etc. It may be easier for a developer to create a script to automatically capture and add all the values than for you to add them manually.

  • Update field values for thousands of assets at once. A developer could use the Search API to find all assets that fit certain criteria and then set the metadata fields for all returned assets to the appropriate values.

  • Capture data from other parts of your application and use that data to assign metadata values to assets that your end-users upload. For example, a programmer could set metadata field values to a customer username, options the customer selected in your application and more, and store that data with the assets they upload, so that this data can then be used for other application features. For example, you could then allow your end users to search for all photos they uploaded or display a page with all photos that customers marked as belonging to a selected category.

  • Your developer could create a small application to monitor changes in an external system, such as a PIM, or status management system, and then those changes could trigger programmatic changes to asset metadata values or the possible values of a metadata field.

For details, see metadata_fields in the Admin API Reference and metadata in the Upload API Reference.

Asset usage reports

There are a few locations in the Cloudinary console where you can view statistics, graphs, and other important information about your account usage:

Dashboard: Just below the account details in your Dashboard, you can view a variety of summary details and trend graphs covering your overall account usage in terms of transformations, total assets, used storage, and used bandwidth. This page also shows all add-ons you've registered to, and your current plan and usage on each.

Dashboard statistics

On the right side of the Dashboard page, you can also view your current plan and limits or upgrade to a new plan.

Account plan limits

Reports: The Reports page has a large variety of usage details that can help you to analyze how your users are interacting with your published assets. It also links to the Error report page. The image below shows selected elements of the report:

Sample DAM reports

Usage notifications

To receive email notifications of your monthly usage, or to be notified when your usage goes above a configurable threshold (paid plans only), select the relevant options in the Users tab > Email preferences section of the console settings.

✔️ Feedback sent!

Rate this page: