Provisioning API reference
Accounts with provisioning API access can create and manage their sub-accounts, users and user groups using the RESTful Provisioning API.
Provisioning API access is available for accounts on a Custom plan upon request.
Overview
The Provisioning API is accessed using HTTPS to endpoints. 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 sub-accounts in the account with ID '16a8ff3b-736b-49a6-85c0-03b69d5a357b':
GET https://api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts
The API uses Basic Authentication over secure HTTP. Your Cloudinary Account ID, Provisioning Key and Provisioning Secret are used for the authentication. These ID's are located in the Cloudinary Management Console under Settings -> Account -> Provisioning API Access, or they can be obtained from the provisioning environment variable available on your management console Dashboard (in the form: CLOUDINARY_ACOUNT_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:
curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/<ACCOUNT_ID>/sub_accounts
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 sub-accounts:
{ "sub_accounts": [ { "cloud_name": "product1", "name": "Product1 Application", "enabled": true, "id": "abcde1fghij2klmno3pqrst4uvwxy5z", "api_access_keys": [ { "key": "123456789012345", "secret": "asdf1JKL2xyz3ABc4s3c5reT01DfaKe" } ], "created_at": "2019-03-15T11:44:48Z" }, { "cloud_name": "product2", "name": "Product2 Application", "enabled": true, "id": "0aaaaa1bbbbb2ccccc3ddddd4eeeee5f", "api_access_keys": [ { "key": "543210987654321", "secret": "T415i5mYs3cr3TkeYN0tR3a77y0o0" } ], "created_at": "2019-04-27T08:00:16Z" } ] }
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 sub-accounts 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:
Pagination
As with the Admin API, you can control the number of results returned in a single request by specifying the max_results parameter, and you can use the returned value of next_cursor to view additional results. For details see Pagination in the Admin API Reference.
Sub-accounts
Manage the sub-accounts of your main account:
Method | Description |
---|---|
GET/accounts/:account_id/sub_accounts |
Get sub-accounts |
GET/accounts/:account_id/sub_accounts/:sub_account_id |
Get sub-account |
POST/accounts/:account_id/sub_accounts |
Create sub-account |
PUT/accounts/:account_id/sub_accounts/:sub_account_id |
Update sub-account |
DELETE/accounts/:account_id/sub_accounts/:sub_account_id |
Delete sub-account |
Get sub-accounts
Return an array of all sub-accounts, or if conditions are specified, return the relevant sub-accounts.
Syntax
GET /accounts/:account_id/sub_accounts
Optional parameters
Parameter | Type | Description |
---|---|---|
enabled | Boolean | Whether to only return enabled sub-accounts (true) or disabled accounts (false). Default: all accounts are returned (both enabled and disabled). |
ids | Array of Strings | A list (SDKs wrap as an array) of up to 100 sub-account 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 sub-accounts with a name that begins with 'product':
Sample response
{ "sub_accounts": [ { "cloud_name": "product2", "name": "Product2 Application", "enabled": true, "id": "0aaaaa1bbbbb2ccccc3ddddd4eeeee5f", "api_access_keys": [ { "key": "543210987654321", "secret": "T415i5mYs3cr3TkeYN0tR3a77y0o0" } ], "created_at": "2016-03-15T11:44:48Z" }, { "cloud_name": "product1", "name": "Product1 Application", "enabled": true, "id": "abcde1fghij2klmno3pqrst4uvwxy5z", "api_access_keys": [ { "key": "123456789012345", "secret": "asdf1JKL2xyz3ABc4s3c5reT01DfaKe" } ], "created_at": "2016-09-27T08:00:16Z" } ] }
Get sub-account
Return the specified sub-account.
Syntax
GET /accounts/:account_id/sub_accounts/:sub_account_id
Required parameters
Parameter | Type | Description |
---|---|---|
sub_account_id | String | The ID of the sub-account to get. |
Optional parameters
Parameter | Type | Description |
---|---|---|
options | Object | See Configuration parameters. |
Example
Return the sub-account with the id of '7f08f1f1fc910bf1f25274aef11d27':
Sample response
{ "cloud_name": "product1", "name": "Product1 Application", "enabled": true, "id": "7f08f1f1fc910bf1f25274aef11d27", "api_access_keys": [ { "key": "123456789012345", "secret": "asdf1JKL2xyz3ABc4s3c5reT01DfaKe" } ], "created_at": "2016-09-27T08:00:16Z" }
Create sub-account
Create a new sub-account. Any users that have access to all sub-accounts will also automatically have access to the new sub-account.
Syntax
POST /accounts/:account_id/sub_accounts
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The display name as shown in the management console. |
Optional parameters
Parameter | Type | Description |
---|---|---|
cloud_name | String | A case-insensitive cloud name comprised of alphanumeric and underscore characters. Use with caution - generates an error if the cloud name is not unique across all Cloudinary accounts. Default: a unique cloud name automatically generated by Cloudinary. |
base_account | String | The ID of another sub-account, from which to copy all of the following settings: Size limits, Timed limits, and Flags. |
enabled | Boolean | Whether the sub-account is enabled. Default: true |
custom_attributes | Object | Any custom attributes you want to associate with the sub-account, as a map/hash of key/value pairs. |
options | Object | See Configuration parameters. |
Example
Create a new sub-account called 'demo account' and set it as disabled:
Sample response
{ "cloud_name": "product3", "name": "Product3 Application", "enabled": false, "id": "555asdf0000zxcvb3456qwerty", "api_access_keys": [ { "key": "135792468054321", "secret": "w4aTi5Y0u6k3YN0773lL1nGyUt0Da8" } ], "created_at": "2016-09-27T11:15:35Z" }
Update sub-account
Update the the specified details of the sub-account.
Syntax
PUT /accounts/:account_id/sub_accounts/:sub_account_id
Required parameters
Parameter | Type | Description |
---|---|---|
sub_account_id | String | The ID of the sub-account to update. |
Optional parameters
Parameter | Type | Description |
---|---|---|
name | String | The display name as shown in the management console. |
cloud_name | String | A case-insensitive cloud name comprised of alphanumeric and underscore characters. Use with caution - generates an error if the cloud name is not unique across all Cloudinary accounts. Note: Can only be changed for accounts with fewer than 1000 images. |
custom_attributes | Object | Any custom attributes you want to associate with the sub-account, as a map/hash of key/value pairs. |
enabled | Boolean | Whether the sub-account is enabled. |
options | Object | See Configuration parameters. |
Example
To disable the sub-account with id '7f08f1f1fc910bf1f25274aef11d27':
Sample response
{ "cloud_name": "product1", "name": "Product1 Application", "enabled": false, "id": "7f08f1f1fc910bf1f25274aef11d27", "api_access_keys": [ { "key": "123456789012345", "secret": "asdf1JKL2xyz3ABc4s3c5reT01DfaKe" } ], "created_at": "2016-09-27T08:00:16Z" }
Delete sub-account
Delete the specified sub-account. 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 sub-account to delete. |
Optional parameters
Parameter | Type | Description |
---|---|---|
options | Object | See Configuration parameters. |
Example
To delete the sub-account 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 or email address 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
{ "users": [ { "id": "139147faa12ce11f22cfaffa84b307", "name": "john_smith", "role": "media_library_user", "email": "john_smith@example.com", "pending": true, "enabled": true, "created_at": "2020-01-13T05:16:06Z", "all_sub_accounts": true }, { "id": "28c84b2aa7924a5e64f949b5403981", "name": "john_jones", "role": "master_admin", "email": "john_jones@example.com", "pending": true, "enabled": true, "created_at": "2019-01-13T05:16:05Z", "all_sub_accounts": true } ] }
Get user
Return the user with the specified ID.
user_id
value is not displayed in the management 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
{ "id": "7f08f1f1fc910bf1f25274aef11d27", "name": "foobar", "role": "master_admin", "email": "email@domain.com", "pending": true, "enabled": true, "created_at": "2019-09-12T11:53:57Z", "all_sub_accounts": false, "groups": [], "sub_account_ids": "555asdf0000zxcvb3456qwerty" }
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 | The list (SDKs wrap as an array) of sub-account IDs that this user can access. Note: This parameter is ignored if the role is specified as master_admin . Default: all sub-accounts. |
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
{ "id": "0abed8dfcc039ea05e2a1d494fd442", "name": "John", "role": "technical_admin", "email": "john@example.com", "pending": true, "enabled": true, "created_at": "2020-09-03T13:33:25Z", "all_sub_accounts": true, "groups": [] }
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 | Array of Strings | The list (SDKs wrap as an array) of sub-account IDs that this user can access. Note: This parameter is ignored if the role is specified as master_admin . |
options | Object | See Configuration parameters. |
Example
To update the role of a user with id '7f08f1f1fc910bf1f25274aef11d27' to 'admin':
Sample response
{ "id": "7f08f1f1fc910bf1f25274aef11d27", "name": "John", "role": "admin", "email": "john@example.com", "pending": true, "enabled": true, "created_at": "2019-09-12T11:53:57Z", "all_sub_accounts": false, "groups": [], "sub_account_ids": "555asdf0000zxcvb3456qwerty" }
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
{ "user_groups": [ { "id": "63a12e42952d888d9cabe7fb38888885", "name": "user_group_1" }, { "id": "1cc3808888154263ac1e5eb2e5c52d61", "name": "user_group_1" } ] }
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
{ "users": [ { "id": "7f08f1f1fc910bf1f25274aef11d27", "name": "John", "email": "john@example.com" } ] }
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
{ "users": [ { "id": "230df1d1fa913bf1f35e74a1f41e25", "name": "John", "email": "john@example.com" } ] }
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':