Programmable Media

Provisioning API reference

Last updated: Mar-17-2024

Accounts with provisioning API access can create and manage their product environments, users and user groups using the RESTful Provisioning API.

Provisioning API access is available upon request for accounts on an Enterprise plan.

Cloudinary's backend SDKs wrap these REST APIs, handle authentication, and enable you to perform these methods using your preferred programming language or framework. This reference provides both SDK and REST/cURL syntax and examples for each endpoint method.

Note
'Product environments' in Cloudinary were previously known as 'sub-accounts'. The Provisioning API endpoints have not changed, and thus all Provisioning API operations relating to product environments are still performed using the sub_accounts endpoints, parameters, response keys, etc.

Related topics
The OpenAPI Specification file for the Provisioning API is available here.

Tip
If you just want to use your SSO for login and don’t need provisioning, you can set up SAML login in the Account Security page of your Console Settings.

Overview

By default, the API endpoint uses the following format:

https://api.cloudinary.com/v1_1/provisioning/accounts/:account_id/:action

For example, to get all product environments (sub_accounts) in the account with ID 16a8ff3b-736b-49a6-85c0-03b69d5a357b:

The API uses Basic Authentication over HTTPS. Your Cloudinary Account ID, Provisioning Key and Provisioning Secret are used for the authentication. These ID's are located in the Cloudinary Console under Settings > Account > Provisioning API Access. You can either pass these values individually or you can use an environment variable composed of those three values in the form: CLOUDINARY_ACCOUNT_URL=account://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@<ACCOUNT_ID>. As with all configuration parameters, you can either set these values globally, or pass them with each call.

You can experiment with returning a list of users in your own Cloudinary account by replacing the PROVISIONING_KEY, PROVISIONING_SECRET, and ACCOUNT_ID in the cURL command below:

For most actions, request parameters are passed as JSON objects and the response is a JSON snippet. The response includes information about the action that was performed as well as any new relevant data. For example, the response from a request to get all product environments (sub_accounts):

The following sections provide additional details on working with the Provisioning API:

Using SDKs with the Provisioning API

In addition to the base REST API, our client libraries provide an easy to use wrapper for the Provisioning API. Request building and authentication are done automatically, and the JSON response is parsed and returned.

For example, the following Java SDK method gets a list of enabled product environments that have a name starting with 'prod':

To access the Provisioning API via and SDK, configure your Account ID, Provisioning Key and Provisioning Secret, located in the Cloudinary Console under Settings > Account > Provisioning API Access. You can:

  • Use the CLOUDINARY_ACCOUNT_URL environment variable, substituting the placeholders with your credentials:
  • Globally configure the Provisioning API using Account ID, Provisioning Key and Provisioning Secret defined separately:

Important
When writing your own applications, follow your organization's policy on storing secrets and don't expose your Provisioning secret.

Error handling

The API returns the status of requests using the HTTP status codes:

  • 200 - OK. Successful.
  • 400 - Bad request.
  • 401 - Authorization required.
  • 403 - Not allowed.
  • 404 - Not found.
  • 409 - Already exists.
  • 420 - Max usage rate exceeded.

The API wrapping of Cloudinary's client libraries report errors by raising applicative exception. In addition, a JSON response with an informative message is returned. For example:

access_keys

Manage the access keys, which include an API key and secret pair, for your product environment (sub-account):

Method Description
GET/accounts/:account_id/sub_accounts/:sub_account_id/access_keys Get access keys
POST/accounts/:account_id/sub_accounts/:sub_account_id/access_keys Generate an access key
PUT/accounts/:account_id/sub_accounts/:sub_account_id/access_keys/:key Update an access key
PUT/accounts/:account_id/sub_accounts/:sub_account_id/access_keys/:key Update an access key
DELETE/accounts/:account_id/sub_accounts/:sub_account_id/access_keys/:key Delete an access key by API key
DELETE/accounts/:account_id/sub_accounts/:sub_account_id/access_keys?name= Delete an access key by name

Get access keys

Return an array of all access keys for a particular product environment.

Syntax

GET /accounts/:account_id/sub_accounts/:sub_account_id/access_keys

Optional parameters

Parameter Type Description
page_size Integer How many entries to display on each page.
page Integer Which page to return (maximum pages: 100). Default: All pages are returned.
sort_by String Which response parameter to sort by. Possible values: api_key, created_at, name, enabled.
sort_order String Control the order of returned keys. Possible values: desc (default), asc.
options Object See Configuration parameters.

Example

Retrieve the access keys in your product environment, sorted by creation date in ascending order (oldest keys first).

Sample response


Generate an access key

Generate a new access key.

Syntax

POST /accounts/:account_id/sub_accounts/:sub_account_id/access_keys

Optional parameters

Parameter Type Description
name String The name of the new access key.
enabled Boolean Whether the new access key is enabled or disabled.
options Object See Configuration parameters.

Example

Generate an access key in the sub account with ID aksdvnklsR1234890 called main_key.

Sample response


Update an access key

Update the name and/or status of an existing access key.

Note
If an access key is dedicated for signing webhook notifications, it can't be disabled. You'll need to replace it with a different dedicated access key for webhook signing via the update method before deletion.

Syntax

PUT /accounts/:account_id/sub_accounts/:sub_account_id/access_keys/:key

Optional parameters

Parameter Type Description
name String The updated name of the access key.
enabled Boolean Enable or disable the access key.
dedicated_for String Designates the access key for a specific purpose while allowing it to be used for other purposes, as well. This action replaces any previously assigned key. Possible values: webhooks
options Object See Configuration parameters.

Example

Disable and rename the access key in the sub account with ID aksdvnklsR1234890, whose API key is 418418418418418, to secondary_key.

Sample response


Delete an access key by API key

Delete an access key with a specified API key from your product environment. You'll no longer be able to access your product environment using the deleted key. This action can't be undone.

Note
An access keys can't be deleted if:
  • It's the only active one in the product environment.
  • It's dedicated for signing webhook notifications. You'll need to replace it with a different dedicated access key for webhook signing via the update method before deletion.

Syntax

DELETE /accounts/:account_id/sub_accounts/:sub_account_id/access_keys/:key

Example

Delete the access key with API key 418418418418418:

Sample response


Delete an access key by name

Delete an access key with a specified name from your product environment. You'll no longer be able to access your product environment using the deleted key. This action can't be undone.

Note
An access keys can't be deleted if:
  • It's the only active one in the product environment.
  • It's dedicated for signing webhook notifications. You'll need to replace it with a different dedicated access key for webhook signing via the update method before deletion.

Syntax

DELETE /accounts/:account_id/sub_accounts/:sub_account_id/access_keys?name=<name>

Example

Delete the access key named secondary_key:

Sample response


sub_accounts (product environments)

Manage the product environments (sub-accounts) of your main account:

Method Description
GET/accounts/:account_id/sub_accounts Get product environments
GET/accounts/:account_id/sub_accounts/:sub_account_id Get product environment
POST/accounts/:account_id/sub_accounts Create product environment
PUT/accounts/:account_id/sub_accounts/:sub_account_id Update product environment
DELETE/accounts/:account_id/sub_accounts/:sub_account_id Delete product environment

Get product environments

Return an array of all product environments, or if conditions are specified, return the relevant product environments.

Syntax

GET /accounts/:account_id/sub_accounts

Optional parameters

Parameter Type Description
enabled Boolean Whether to only return enabled product environments (true) or disabled product environments (false). Default: all product environments are returned (both enabled and disabled).
ids Array of Strings A list (SDKs wrap as an array) of up to 100 product environment IDs. When provided, other parameters are ignored.
prefix String Returns accounts where the name begins with the specified case-insensitive string.
options Object See Configuration parameters.

Example

Return all enabled product environments with a name that begins with 'product':

Sample response


Get product environment

Return the specified product environment.

Syntax

GET /accounts/:account_id/sub_accounts/:sub_account_id

Required parameters

Parameter Type Description
sub_account_id String The ID of the product environment to get.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return the product environment with the id of '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Create product environment

Create a new product environment. Any users that have access to all product environments will also automatically have access to the new product environment.

Syntax

POST /accounts/:account_id/sub_accounts

Required parameters

Parameter Type Description
name String The display name as shown in the Cloudinary Console.

Optional parameters

Parameter Type Description
cloud_name String A case-insensitive string comprised of between 2-128 alphanumeric and hyphen characters, starting with a letter. Note that cloud names must be unique across all Cloudinary accounts. An error is returned if the requested name already exists. Default: a unique string automatically generated by Cloudinary.
base_sub_account_id String The ID of another product environment, from which to copy all of the following settings: Size limits, Timed limits, and Flags. The parameter is called base_account in some SDKs.
custom_attributes Object Any custom attributes you want to associate with the product environment, as a map/hash of key/value pairs.
options Object See Configuration parameters.

Example

Create a new product environment called 'demo account':

Sample response


Update product environment

Update the specified details of the product environment.

Syntax

PUT /accounts/:account_id/sub_accounts/:sub_account_id

Required parameters

Parameter Type Description
sub_account_id String The ID of the product environment to update.

Optional parameters

Parameter Type Description
name String The display name as shown in the Cloudinary Console.
cloud_name String A case-insensitive cloud name comprised of between 2-128 alphanumeric and hyphen characters, starting with a letter. Note that cloud names must be unique across all Cloudinary accounts. An error is returned if the requested name already exists. Note: Can only be changed for accounts with fewer than 1000 images.
custom_attributes Object Any custom attributes you want to associate with the product environment, as a map/hash of key/value pairs.
enabled Boolean Whether the product environment is enabled. Default: true
options Object See Configuration parameters.

Example

To disable the product environment with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Delete product environment

Delete the specified product environment. Supported only for accounts with fewer than 1000 images.

Syntax

DELETE /accounts/:account_id/sub_accounts/:sub_account_id

Required parameters

Parameter Type Description
sub_account_id String The ID of the product environment to delete.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

To delete the product environment with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


users

Manage the users for your account:

Method Description
GET/accounts/:account_id/users Get users
GET/accounts/:account_id/users/:user_id Get user
POST/accounts/:account_id/users Create user
PUT/accounts/:account_id/users/:user_id Update user
DELETE/accounts/:account_id/users/:user_id Delete user

Get users

Returns an array of all users in the account, or if conditions are specified, returns the relevant users.

Syntax

GET /accounts/:account_id/users

Optional parameters

Parameter Type Description
pending Boolean Whether to only return pending users. Default: false (all users)
ids Array of Strings A list (SDKs wrap as an array) of up to 100 user IDs. When provided, other parameters are ignored.
prefix String Returns users where the name begins with the specified case-insensitive string.
sub_account_id String Only returns users who have access to the specified account.
options Object See Configuration parameters.
last_login Boolean Specifies a date range for last login.
from String All last logins after this date, given in the format: yyyy-mm-dd
to String All last logins before this date, given in the format: yyyy-mm-dd
union_type String Whether to return users who last logged in within the specified date range (include), or those who didn't last log in within the range (exclude). Possible values: include, exclude Default: include

Example

Return all users with a name that begins with 'john':

Sample response


Get user

Return the user with the specified ID.

Note
The user_id value is not displayed in the Cloudinary Console, but it is returned when creating a user. You can also retrieve it based on the user's name or email, using the get users operation to return a user by prefix.

Syntax

GET /accounts/:account_id/users/:user_id

Required parameters

Parameter Type Description
user_id String The ID of the user to get.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return the user with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Create user

Create a new, enabled user for the account with the status pending.

Syntax

POST /accounts/:account_id/users

Required parameters

Parameter Type Description
name String The user's name.
email String A unique email address, which serves as the login name and notification address.
role String The role to assign. Possible values: master_admin, admin, billing, technical_admin, reports, media_library_admin, media_library_user

Optional parameters

Parameter Type Description
sub_account_ids Array of Strings A comma-separated list (SDKs wrap as an array) of product environment IDs that this user can access. Note: This parameter is ignored if the role is specified as master_admin. Default: all product environments.
enabled Boolean Whether the user is enabled. Default: true
options Object See Configuration parameters.

Example

Create a new user named 'John', with an email address of 'john@example.com' and a role of 'technical_admin':

Sample response


Update user

Update the details of a specified user.

Syntax

PUT /accounts/:account_id/sub_accounts/:user_id

Required parameters

Parameter Type Description
user_id String The ID of the user to update.

Optional parameters

Parameter Type Description
name String The user's name.
email String A unique email address, which serves as the login name and notification address.
role String The role to assign. Possible values: master_admin, admin, billing, technical_admin, reports, media_library_admin, media_library_user
sub_account_ids String A comma-separated list (SDKs wrap as an array) of product environment IDs that this user can access. Note: This parameter is ignored if the role is specified as master_admin.
enabled Boolean Whether the user is enabled.
options Object See Configuration parameters.

Example

To update the role of a user with id '7f08f1f1fc910bf1f25274aef11d27' to 'admin':

Sample response


Delete user

Delete a user with the specified ID.

Note
When you delete a user from your system, they are deactivated and no longer count against your account's user quota. Nevertheless, specific types of information related to that user are still displayed in the Media Library and Activity Reports where relevant, for example when a comment is identified as having been made by the deleted user. For more information, see Deleting users.

Syntax

DELETE /accounts/:account_id/users/:user_id

Required parameters

Parameter Type Description
user_id String The ID of the user to delete.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Delete the user with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


user_groups

Manage the groups for the users in your account:

Method Description
GET/accounts/:account_id/user_groups Get user groups
GET/accounts/:account_id/user_groups/:group_id Get a user group
GET/accounts/:account_id/user_groups/:group_id/users Get the users in a user group
POST/accounts/:account_id/user_groups Create a user group
POST/accounts/:account_id/user_groups/:group_id/users/:user_id Add a user to a group
PUT/accounts/:account_id/user_groups/:group_id Update a user group
DELETE/accounts/:account_id/user_groups/:group_id Delete a user group
DELETE/accounts/:account_id/user_groups/:group_id/users/:user_id Remove a user from a group

Get user groups

Return an array of all user groups in the account.

Syntax

GET /accounts/:account_id/user_groups

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return all user groups:

Sample response


Get user group

Return a user group with the specified ID.

Syntax

GET /accounts/:account_id/user_groups/:group_id

Required parameters

Parameter Type Description
group_id String The ID of the user group to get.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return the user group with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Get user-group users

Return the users in the group with the specified ID.

Syntax

GET /accounts/:account_id/user_groups/:group_id/users

Required parameters

Parameter Type Description
group_id String The ID of the user group.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return the users in the group with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Create user group

Create a new user group for the account.

Syntax

POST /accounts/:account_id/user_groups

Required parameters

Parameter Type Description
name String The name for the user group.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Create a new user group named 'Designers':

Sample response


Add user to group

Add a user to a group with the specified ID.

Syntax

POST /accounts/:account_id/user_groups/:group_id/users/:user_id

Required parameters

Parameter Type Description
group_id String The ID of the user group.
user_id String The ID of the user.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Add the user with id '230df1d1fa913bf1f35e74a1f41e25' to the group with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Update user group

Update the name of a specified user group.

Syntax

PUT /accounts/:account_id/user_groups/:group_id

Required parameters

Parameter Type Description
group_id String The ID of the user group to update.
name String The name for the user group.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

To update the name of a group with id '7f08f1f1fc910bf1f25274aef11d27' to 'Designers':

Sample response


Delete user group

Delete a user group with the specified ID.

Syntax

DELETE /accounts/:account_id/user_groups/:group_id

Required parameters

Parameter Type Description
group_id String The ID of the user group to delete.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Delete the user group with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response


Remove user from group

Remove a user from a group with the specified ID.

Syntax

DELETE /accounts/:account_id/user_groups/:group_id/users/:user_id

Required parameters

Parameter Type Description
group_id String The ID of the user group.
user_id String The ID of the user.

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Remove the user with id '230df1d1fa913bf1f35e74a1f41e25' from the group with id '7f08f1f1fc910bf1f25274aef11d27':

Sample response

✔️ Feedback sent!

Rate this page: