Digital Asset Management
Provisioning API reference
Last updated: Sep-28-2023
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.
sub_accounts endpoints, parameters, response keys, etc.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, or they can be obtained from the provisioning environment variable available on your Cloudinary Console Dashboard (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':
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 |
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. |
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. |
Example
Generate and enable an access key called main_key.
Sample response
Update an access key
Update the name and/or status of an existing access key.
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. |
Example
Disable and rename the access key with API key 418418418418418 to secondary_key.
Sample response
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. |
Example
Return all users with a name that begins with 'john':
Sample response
Get user
Return the user with the specified ID.
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. |
| 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. |
| 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.
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
Error
Rate this page:
