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

User provisioning

Last updated: Nov-17-2026

If your account has multiple users, you can use roles to control access and permissions within the Console, in line with your data and asset governance policy.

Start by identifying key workflows, assets, and resources that each user needs to access, as well as actions they should be able to perform.

Notes
  • Every user who accesses the Console requires a separate seat license.
  • Users and user groups are configured on the account level, so you can manage them from within any of your product environments.
  • This page 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.

Provisioning API

This guide focuses primarily on provisioning users from the User Management page of the Cloudinary Console. However, accounts with access to the Provisioning API can also create and manage users and user groups programmatically using the RESTful Provisioning API.

Provisioning API access is available for accounts on an Enterprise plan. If you don’t currently have access and would like to explore your options, contact us.

The Provisioning API uses Basic Authentication over HTTPS. Your account management key and account management secret are used for the authentication. These credentials (as well as your ACCOUNT_ID) are located in the Account Management Keys page of the Console Settings.

Note
Account management keys were previously referred to as account API keys and provisioning API keys.

The Provisioning API provides the following capabilities:

  • User configuration endpoints: Manage users by retrieving a list of users and details of a single user, creating a user, updating details, or deleting users.

  • User group management endpoints: Manage user groups by creating groups, updating group details, retrieving a list of groups, retrieving group information including a list of members, adding or removing users, and deleting groups.

Notes

For more details, see the Provisioning API reference.

Changing user roles via the API

To update a user, including their roles, send a PUT request to the Update user endpoint with the user's ID in the path. You can find the ID in the id field returned by the Get users endpoint. You can also assign roles to users, groups, and keys with the Permissions API. See Assign roles to a principal.

For example, this request gives a user the Master Admin role at the account level and in all product environments:

To send the same request from Postman or another API client, use Basic Auth with your account management key as the username and your account management secret as the password, and send the JSON as the raw request body.

  • Adding and removing roles: Set operation to add or remove. Adding a role doesn't remove the user's other roles, so to replace a role, send a second request that removes the old one.
  • Role IDs: Find the IDs of system roles in the System roles and policies list or the public catalog. A product environment role without a scope_id applies to all product environments. To limit it to one product environment, add "scope_id": "<PRODUCT_ENVIRONMENT_ID>" to the role.
  • Legacy role field: Use role_management instead of the deprecated role field (for example, "role": "master_admin"). You can't send both in the same request. If your account still uses legacy permissions, use role. The API ignores role_management on those accounts.
  • Checking the result: The response doesn't list the user's roles. To check them, see Inspecting role assignments.
  • sub_account_ids and all_sub_accounts: The response includes all_sub_accounts, which you can't set directly. Sending a list of product environment IDs in sub_account_ids sets it to false, and sending an empty list gives the user access to all product environments and sets it to true.

Troubleshooting a 404 error
The sub_accounts/<ID> path takes a product environment ID, and PUT on it updates a product environment, not a user. If you send a user ID to that path, the request fails with a 404 error and the message sub account not found. To update a user or their roles, use the users/<USER_ID> path shown above. If that path returns Cannot find user, check that the ID belongs to a user in the account in the URL.

User configuration

The My Profile page of Console Settings includes your personal profile details, email preferences, and two-factor authentication setup. Any user can update their personal information here.

To configure settings for all account users (adding, modifying, or removing users), you need user management permissions. The Master Admin and Admin system roles include this by default. Enterprise customers can also grant it via custom roles.

  • You can view and manage all account users, including adding users, removing users, changing their roles, and more.
  • You can activate SAML login for your organization from the Account Security page of the Console Settings.

Tip
If you want to add users over and above your plan's limit, you could either upgrade your plan, or, if you're on a paid plan, separately purchase additional user subscriptions. For more information, see Managing additional user subscriptions.

Root user

The Root User is automatically created in a Cloudinary account as the first user and holds permanent, full administrative access. This user is essential to account management, is clearly marked in the interface, and is the only user who can cancel the account. The Root User is subject to the following restrictions:

  • Can't be deleted, disabled, force-logged out, or have its password revoked

  • Can't be assigned to roles

  • Is always assigned to all product environments

Having a root user ensures there is always a reliable point of authority with full access to manage and maintain the account.

Notes
  • You can't change or replace the root user yourself in the Console. To transfer root user responsibilities (for example, when the root user leaves your organization) submit a Support ticket. Support updates the root user for your account.
  • Only accounts created on or after June 5, 2025 include a root user. If you have a root user, it's visibly labeled in the Console.

Managing users

You can manage account users within the Console in one of the following ways:

Note
Enterprise customers can also manage users via a script, using the Provisioning API.

Adding new users

You can add up to five users at a time (depending on how many users your plan allows) by either:

For each user, you can set:

  • User Details: Enter the email address, first name, and last name for all the users you're adding. Each user you create will receive an email that requires confirmation to this address. This email address is also used for logging in to Cloudinary.

    Note
    If you'd like to prevent users with email addresses on your domain from signing up for separate free accounts, which would prevent you from adding them to your main account as a user, please contact support.
  • Groups: Instead of assigning roles to individual users, assign those roles to user groups. Group members inherit all the global and content roles assigned to the group. Product environment access isn't inherited through groups, so you need to make sure the users are individually assigned product environment access for the roles in those product environments to take effect.

  • Access Management: Assigns the user's level of access in the Console, including roles and product environment access.

    • For quick setup, select an access bundle, a predefined set of roles for a common user type, from the Access Management dropdown. A bundle includes system roles, which may be account-level roles, product environment-level roles applied across all product environments, or both.
      Tip
      To see exactly which roles the bundle you select assigns, and optionally further refine the selected roles, expand Manage access details.
    • For granular control, select Custom access from the Access Management dropdown, or expand Manage access details to select the individual roles for the users you're adding on both the account and product environment levels. Available roles can include both predefined system roles as well as custom roles (Enterprise only) that an administrator on your team built from selected permissions.
      • Account Roles: Select roles that provide access on the account level, such as provisioning users and accessing the Billing pages in the Console Settings.
      • Product Environment Roles: Select roles that provide access on the product environment level, such as defining upload behavior, setting named transformations, and granting full access to the Media Library.
        Note
        Product environments were previously referred to as sub-accounts.
        • If your account includes more than one product environment, you can assign the selected roles to All product environments, or manually select up to 30 specific environments to assign them to.
        • Assigning roles to users doesn't automatically give them access to those product environments. To ensure users can access what their roles allow, explicitly grant them access to each product environment from the User Management page of the Console Settings. For a specific user, click their Product Environments field in the table.

          For details, see Define access when inviting new users.

Tip
For more information about roles, permissions, and product environment access, see Roles and Permissions. For full instructions on inviting users, assigning roles, and managing groups, see Manage and assign roles.

Updating users

You can update users from the User Management page in Console Settings:

  • To edit a user's details: Select Edit Details from the (3-dots) option menu for the user. You can edit basic details such as email, first name, last name, and groups.
  • To assign product environments: Click the entry in the user's Product Environment column. You can assign a user access to all product environments, or manually select up to 30 specific ones.
  • To manage user roles: Select Assign Roles from the (3-dots) option menu for the user. See Assign global roles to existing users.

Tip
Cloudinary re-sends an invite after saving, which is especially useful when updating contact information.

Resetting user passwords

You can initiate a password reset for an individual user to ensure account security.

To initiate a password reset, select Reset Password from the kebab menu at the end of a specific user's row in the User Management page within your Console Settings. This action:

  • Immediately terminates the user's active session.
  • Invalidates the old password, rendering it unusable for login. The user must set a new password to regain access.
  • Triggers an email containing a link that allows the user to set a new password. Alternatively, users can initiate the password reset process themselves by clicking on the Forgot your password link on the login page.

Users undergoing a password reset are marked with a specific status in the User Management table, clearly indicating that they're in the process of changing their password. This makes it easy to identify and manage such users.

Note
The password reset action applies exclusively to users who originally registered with a username and password. Users who signed up through Google, Github, or SAML don't fall under this category.

Force immediate logout

You can initiate a force logout for an individual user to ensure account security. This feature is particularly helpful when you prefer not to require a password reset, or for users logged in via Google, GitHub, or SAML, who lack passwords, making it impossible to link session termination with a password reset.

To force a user to logout, select Force Logout from the kebab menu at the end of a specific user's row in the User Management page within your Console Settings. This action terminates the user's active session within ten minutes.

Tip
To efficiently terminate sessions for multiple users without the need to do it individually, contact support.

Deleting users

To delete a user, select Delete from the kebab menu at the end of a specific user's row in the User Management page within your Console Settings.

Alternatively, Enterprise customers with access to the Provisioning API can disable users programmatically using the Delete user endpoint.

When a user leaves your organization and needs to be removed from your system, certain information about them must still be retained. This includes details like the collections they created and the assets they uploaded.

To address those needs, user deletion is handled in the following ways:

  • The deleted user's status is changed to Inactive on the User Management page in the Console Settings. This status is permanent, and the user can't be reactivated.
  • Throughout the user interface, a label indicating Inactive is displayed wherever the deleted user is mentioned.
  • Deleted users no longer count against your account's user quota.
  • You have the option to reuse the deleted user's email and assign it to a completely new user.

Note
To learn how deleted users are reflected in Assets, see Deleting users in the Assets user Guides.

Managing additional user subscriptions

You can see the maximum number of users that you're eligible for via your base plan in the panel on the right side of your Account Settings page of the Cloudinary Console. If you need to increase your user limit, you can upgrade your plan by clicking the Change Plan button.

Alternatively, you can purchase additional user subscriptions over and above your plan's limit. If you've reached the maximum number of users allowed for your plan, a banner will appear in the User Management page within your Console Settings. Click the Change user limit link displayed in the banner. You can extend your limit by up to 20 additional user subscriptions, with no need to switch plans.

Afterwards, you can increase or decrease the number of additional user subscriptions on your account anytime.

Note
This option is available only to customers that subscribed to Cloudinary directly (not via a different provider like Heroku or AWS), are on a paid plan, and aren't on an Enterprise or custom plan.

For additional help, or to add more than 20 additional users, contact support.

SAML/SSO login

Find the option to activate SAML (SSO) login in the Account Security page of the Console Settings:

SAML Login: This option enables the administrator to activate SAML (SSO) login. This can enable users in your organization to log in using the same authentication system that they 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 choose whether to log in either via the SSO application or via the Cloudinary Console login window. 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.

Notes
  • If your account has SAML (SSO) login enabled and you use the Media Library Widget or one of our Integrations, you must allowlist the domain console.cloudinary.com. If you need assistance, contact Support.
  • 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 SAML login 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.

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars