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.

The majority of your creative team will probably work primarily in the Media Library. Thus, when you assign any of your teammates 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 with user groups or individual users, as well as invite those teammates to collections, 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 teammates 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, click from the top left toolbar of the Media Library, and select Preferences from the 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.

The default settings in the Media Library Preferences provide a good starting place for your Digital Asset Management activities. However, each organization should review all the available options in the Media Library Preferences pane to determine the settings that best answer its needs.


This feature is available by default to DAM customers on all plans. If you are eligible and this feature is not yet activated on your account, contact support.

In the Media Library Preferences, you can customize the user interface for your account or sub-account by setting the default display language. The selected language becomes the default language for the Media Library, Manage Structured Metadata page (admins only), as well as for publicly shared collections and media portals.

Individual users in the DAM as well as viewers of publicly shared collections and media portals can switch languages in the relevant interface.

For users within the DAM, the language they select is a global setting that applies to all sub-accounts they have access to.

Apps for DAM

You can customize and enhance the Media Library core product by selecting apps to add to your account or sub-account. Enable the apps that are relevant to your DAM users from the set of apps that have been made available.

To access the Media Library apps, click from the top left toolbar of the Media Library, and select Apps from the navigation pane.

Apps selection page

Read the description on the cover of each app and click Learn more... for more information about what each app has to offer, including a quick demo. Then, enable the ones that are useful to you and your team. Once you've enabled your apps, you can access them from the relevant menus in the Media Library.


  • The Apps for DAM pane is available for users with admin roles. Changes to these options apply for all users of the account or sub-account.
  • Visit this page periodically to check for additional apps that Cloudinary may make available.
  • If an app has been custom-built for your account or sub-account, that app will appear under the heading Built-in apps. Built-in apps can't be directly disabled from this page. If you want to disable a built-in app, contact support.

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 for each account or sub-account. 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 its 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 mandatory, 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

Defining how metadata is handled on upload

This feature is available by default to DAM customers on all plans. If you are eligible and this feature is not yet activated on your account, contact support.

You can control whether users are prompted to enter structured metadata values on every upload, or only when there are mandatory fields without default values, in the Request structured metadata on upload section of the Media Library Preferences. When users are prompted to enter metadata while uploading, they can only continue once they've filled in valid values for all mandatory fields. For more details on structured metadata and uploading, see Structured metadata on upload.

You can also determine how tags and contextual metadata are handled when existing assets are overwritten in the Keep existing metadata when uploading newer versions of an asset section of the Media Library Preferences. When this option is selected, existing tags and contextual metadata are kept when existing assets are overwritten. Otherwise, they are deleted.

When uploading via the API, the Keep existing metadata when uploading newer versions of an asset determines the behavior of tags, contextual metadata, and structured metadata. Unless this option is selected, metadata of assets overwritten via the API is deleted. Coordinate with your development team when changing this setting.

Adding structured metadata fields

From the Media Library Preferences, click Manage Structured Metadata to open the Manage Structured Metadata page and then follow the steps shown in the animations below or follow the written instructions.

Watch and learn: Create your first field (numeric)

Watch and learn: Create a multi-select field

Read about how to create fields

These steps walk you through the process shown in the above animations, with some additional clarifications:

  1. 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.

  2. 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.
  • 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.
  • After you define a default value for a field, that value appears as the default value for any asset that is subsequently uploaded to the Media Library. The field value will not be set retroactively for assets that were uploaded previously.
  • When you define a field as hidden, you cannot initially assign it a default value, nor can you set it to mandatory. You can change the mandatory setting and assign a default value (as well as determining when it will be displayed) using conditional metadata rules.
  • You have a few ways to make sure that mandatory fields receive values:

    • Define fixed default values when defining the fields.
    • Create conditional metadata rules that assign them default values when they become visible.
    • Allow users to set the values when they are prompted during upload.

    Keep in mind that if you don't assign default values for mandatory fields, any developers in your organization must ensure that they pass field values for mandatory fields every time they upload an asset via the API. If they don't, their upload calls will fail.

  • Once a mandatory 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 mandatory, the field will initially remain untouched. However, if a user clicks in a mandatory field and then exits it without setting a value, they are notified that the field is mandatory.

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, changing the mandatory 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. You can't delete a field if there are metadata rules configured that cause other fields to depend on it.

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.

Managing conditional metadata rules

When setting up structured metadata fields, you may want to design it so that some fields depend on the values entered in others, meaning that some fields or field values only become relevant if certain selections are made or conversely some fields or values should not be available under certain conditions.

This feature is available only to Cloudinary customers on an Enterprise plan.

Conditional metadata rules allow you to set up dependencies and hierarchical relationships between structured metadata fields and field options. This allows you to:

  • Enable/disable (show/hide) another metadata field based on the value selected for a metadata field.
  • Activate options displayed for a particular metadata field based on the value specified in another field.
  • Set the default metadata value in a particular field based on the value specified in another field.

Some popular use cases for conditional metadata include:

  • High-level file type selection, for example: setting metadata fields on different types of content such as image, video and document.
  • Support segmenting into categories, for example: product imagery vs lifestyle photography.
  • Document asset usage rights, for example: stock imagery.
  • Support large organizations with multiple metadata schemas.

For example, one of the metadata fields can include various category values for photos on a company intranet site, such as 'Employee', 'Conference', and 'Culture'. You could set up rules based on these values as follows:

  1. Selecting 'Employee' in the Category metadata field enables (displays) the Team metadata field with values such as 'R&D', 'Product' or 'HR'.
  2. Selecting 'R&D' for the Team metadata field enables the Role metadata field with values such as 'QA', 'Devops' or 'Backend'.
  3. Selecting 'QA' for the Role metadata field enables the Name metadata field with the members of the QA team: 'John Smith' or 'Jane Kelly'. If Devops had been selected for the Role metadata field, then the Name field would be enabled with members of the Devops team: 'Paul Green' or 'Mary Rose'.

Adding rules

You can add one or more rules to a field, and each rule can have one or more conditions and actions for more information.

When you configure several rules on a single field, it's important to consider their order carefully because each subsequent rule can overwrite the actions of the rules before it. For example, one rule can add options to the field's multiple-selection list and another can remove or change them; one can show the field and another can hide it; one can add a default value and another can change it.

  1. From the Media Library Preferences, click Manage Structured Metadata to open the Manage Structured Metadata page.

  2. Select the field whose behavior you want to set as a result of the condition you are adding. For example, if selecting the value Red from the Color field (condition) causes Pink and Maroon to be displayed in the Color shade field (result), then you should create the rule on the Color shade field.

    If you want this field to remain hidden unless a certain condition is met, enable Hide this field. If the field is hidden, it cannot initially be a mandatory field, and it cannot contain a default value. However, you can add a rule whose action displays the field, assigns it a default value, and / or makes it mandatory.

  3. In the right-hand panel, click Manage rules, then click Create a rule to open the Create Rule screen and enter a descriptive Rule name.

  4. Click Add condition and select the field and condition options that express your case.

    The condition is presented as a natural English sentence with the following structure:

    When the field you select Is empty or Is populated            OR Includes or Equals a value you select...
  5. Optionally, enter additional conditions and select Match one (OR) or Match all (AND).

  6. Click Add action to determine what happens to your selected field when the condition you set is met. The Action summary table describes the actions you can set and gives a sample use case for each one.

Structured metadata rule creation

Action summary table

Action Description Use case example
Show field The dependent field is hidden by default and displayed if the condition is met. If the value of the Category field is Employee, the Department field is displayed.
Hide field The dependent field is displayed by default and is hidden if the condition is met. The default value for the Country field is USA, and the State field appears. If the value of for the Country field is changed to England, the State field becomes hidden.
Set field as mandatory The dependent field becomes mandatory. All assets can optionally receive an Expiration date, but If the asset's Copyright field is set to Yes, then the Expiration date field becomes mandatory.
Set field as optional The dependent field becomes optional. Color is crucial to track for most assets and is therefore set to mandatory by default, unless the asset's Category is Oldies, in which case Color is not always a factor, so the Color field can be set to optional.
Set default value(s) A default value is set for the dependent field. This condition can be used with the Show field action. For example, the value Employee is chosen from the field Category, causing the Department field to be displayed. When the field is displayed, it's assigned a default value, R&D.
Append values Automatically sets one or more values to the dependent field and displays them as selected (only if the user hasn't made a selection manually). If the value Snow is selected for the Category field, the option Winter campaign is appended to the Campaign field, and is displayed as a selected value in that field.
Show all options All available options of a single or multiple-selection list in the dependent field are displayed, when some of the options configured for the list may have previously been hidden. When Usage Rights is set to Public, the asset can be displayed in all possible Venues, as opposed to when Usage Rights is set to Internal and a limited number of Venues are available.
Show no options Clears all available options in a single or multiple-selection list in the dependent field. This is useful when you want to start with an empty list and add displayed values as conditions are met. The Color Shades field is initially cleared using the Show no options action. When the color Blue is selected from the Color field, the Color Shades: Light Blue and Navy options are displayed using the Show the following additional options... action. When the color Red is added, red Color Shades options are additionally displayed.
Show only the following options... Defines the available options in the single or multiple-selection list in the dependent field. The Roles field displays different options based on the Department chosen.
Show the following additional options... Additional options (that may have been hidden) are added to the single or multiple-selection list in the dependent field. Certain core Categories of images are used all year round, but in Summer the category Swimwear is added.

Viewing and updating rules

To view and update rules:

  1. From the Media Library Preferences, click Manage Structured Metadata to open the Manage Structured Metadata page.
  2. If a field has a rule already configured, Has rules appears in the field description. Select the field whose rules you want to view or update and click Manage rules. A summary of the configured rules for that field appears.
  3. Click Edit and make changes to a rule. Drag and drop the rule to its desired position.

Structured metadata rule summary

Conditional metadata rule considerations

  • You can add multiple conditions to determine a specific action. For example, you may want a specific list of Videographers to appear only if the value for the File type field is Video and the value for the Category field is Nature.

    If your action depends on multiple conditions, you can select Match one (OR) to apply the action when ANY one of the conditions are met, or Match all (AND) to apply the action only when ALL of the conditions are met.

  • Actions are grouped according to their similar functions. (Show field is grouped with Hide field, Set field as mandatory is grouped with Set field as optional, etc.) You can only add one action from the same group in a single rule. For example, if you've already added Show only the following options..., you won't be able to also add Show the following additional options.... However, you can add a new rule to the field to set the desired action.

  • From the Manage Structured Metadata page, order your fields hierarchically so that when dependent fields appear, they are displayed directly below the fields they depend on.

  • When users update metadata in bulk, values in dependent fields may be automatically deleted if values of fields that they depend on are changed.

  • A field that has dependencies can't be deleted.

Structured metadata is always available to the user for viewing and setting. However, you can hide contextual metadata from the user's view in the Media Library Preferences.

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: