Provisioning API reference

Accounts with provisioning API access (available upon request for Premium and higher plans) can create and manage their sub-accounts, users and user groups using the RESTful Provisioning API.

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':

Copy to clipboard
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:

Copy to clipboard
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:

Copy to clipboard
{
  "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':

Copy to clipboard
account.getSubAccounts(true, null, "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:

Copy to clipboard
{ "error": { "message": "User not found" } }

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

Python:
Copy to clipboard
sub_accounts(enabled=None, ids=None, prefix=None, **options)
Node.js:
Copy to clipboard
sub_accounts(boolean enabled, string[] ids, string prefix, object options);
Java:
Copy to clipboard
subAccounts(Boolean enabled, List<String> ids, String prefix, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.sub_accounts(True, prefix = "product")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.sub_accounts(true, null, "product")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.subAccounts(true, null, "product");
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "enabled": "true",
        "prefix": "product"
      }' \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
sub_account(sub_account_id, **options)
Node.js:
Copy to clipboard
sub_accounts(string sub_account_id, object options);
Java:
Copy to clipboard
subAccount(String subAccountID, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.sub_account("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.sub_account("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.subAccount("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
create_sub_account(name, cloud_name=None, custom_attributes=None, enabled=None, base_account=None, **options)
Node.js:
Copy to clipboard
create_sub_account(string name, string cloud_name, object custom_attributes, boolean enabled, string base_account, object options);
Java:
Copy to clipboard
createSubAccount(String name, String cloudName, Map customAttributes, Boolean enabled, String baseAccount, Map options);

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 enabled:

Python:
Copy to clipboard
cloudinary.provisioning.account.create_sub_account("demo account", enabled = False)
Node.js:
Copy to clipboard
cloudinary.provisioning.account.create_sub_account("demo account", null, null, false)
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.createSubAccount("demo account", null, ObjectUtils.emptyMap(), false, null);
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "name": "demo account",
        "enabled": "false"
      }' \
  -X POST \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts

Sample response

Copy to clipboard
{
  "cloud_name": "product3",
  "name": "Product3 Application",
  "enabled": true,
  "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

Python:
Copy to clipboard
update_sub_account(sub_account_id, name=None, cloud_name=None, custom_attributes=None, enabled=None, base_account=None, **options)
Node.js:
Copy to clipboard
update_sub_account(string sub_account_id, string name, string cloud_name, object custom_attributes, boolean enabled, object options);
Java:
Copy to clipboard
updateSubAccount(String subAccountId, String name, String cloudName, Map customAttributes, Boolean enabled, Map options);

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':

Python:
Copy to clipboard
update_sub_account("7f08f1f1fc910bf1f25274aef11d27", enabled = False)
Node.js:
Copy to clipboard
cloudinary.provisioning.account.update_sub_account("7f08f1f1fc910bf1f25274aef11d27", null, null, {}, false)
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.updateSubAccount("7f08f1f1fc910bf1f25274aef11d27", null, null, {ObjectUtils.emptyMap()}, false);
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "enabled": "false"
      }' \
  -X PUT \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
delete_sub_account(sub_account_id, **options)
Node.js:
Copy to clipboard
delete_sub_account(string sub_account_id, object options);
Java:
Copy to clipboard
deleteSubAccount(String subAccountID, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.delete_sub_account("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.delete_sub_account("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.deleteSubAccount("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "message": "ok"
}

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

Python:
Copy to clipboard
users(user_ids=None, sub_account_id=None, pending=None, prefix=None, **options)
Node.js:
Copy to clipboard
users(boolean pending, string[]] ids, string prefix, string sub_account_id, object options);
Java:
Copy to clipboard
Users(Boolean pending, List<String> ids, String prefix, String subAccountId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.users(prefix = "john")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.users(null, null, "john")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.Users(null, null, "john", null);
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "prefix": "john"
      }' \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users

Sample response

Copy to clipboard
{
  "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.

Note
The 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

Python:
Copy to clipboard
user(user_id, **options)
Node.js:
Copy to clipboard
user(string user_id, object options);
Java:
Copy to clipboard
user(String userID, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.user("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.user("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.user("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
create_user(name, email, role, sub_account_ids=None, **options)
Node.js:
Copy to clipboard
create_user(string name, string email, string role, string[] sub_accounts_ids, object options);
Java:
Copy to clipboard
createUser(String name, String email, String role, List<String> subAccountsIds, Map options);

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_accounts 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':

Python:
Copy to clipboard
cloudinary.provisioning.account.create_user("John", "john@example.com", "technical_admin")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.create_user("John", "john@example.com", "technical_admin")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.createUser("John", "john@example.com", "technical_admin", null);
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "name": "John",
        "email": "john@example.com",
        "role": "technical_admin"
      }' \
  -X POST \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users

Sample response

Copy to clipboard
{
  "cloud_name": "product3",
  "name": "Product3 Application",
  "enabled": true,
  "id": "555asdf0000zxcvb3456qwerty",
  "api_access_keys": [
    {
      "key": "135792468054321",
      "secret": "w4aTi5Y0u6k3YN0773lL1nGyUt0Da8"
    }
  ],
  "created_at": "2016-09-27T11:15:35Z"
}

Update user

Update the details of a specified user.

Syntax

PUT /accounts/:account_id/sub_accounts/:user_id

Python:
Copy to clipboard
update_user(user_id, name=None, email=None, role=None, sub_account_ids=None, **options)
Node.js:
Copy to clipboard
update_user(string user_id, string name, string email, string role, string[] sub_accounts_ids, object options);
Java:
Copy to clipboard
updateUser(String userId, String name, String email, String role, List<String> subAccountsIds, Map options);

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 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':

Python:
Copy to clipboard
cloudinary.provisioning.account.update_user("7f08f1f1fc910bf1f25274aef11d27", role = "admin")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.update_user("7f08f1f1fc910bf1f25274aef11d27", null, null, "admin")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.updateUser("7f08f1f1fc910bf1f25274aef11d27", null, null, "admin", null);
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "role": "admin"
      }' \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
delete_user(user_id, **options)
Node.js:
Copy to clipboard
delete_user(string user_id, object options);
Java:
Copy to clipboard
deleteUser(String userId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.delete_user("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.delete_user("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.deleteUser("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "message": "ok"
}

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

Python:
Copy to clipboard
user_groups(**options)
Node.js:
Copy to clipboard
user_groups(object options);
Java:
Copy to clipboard
userGroups(Map options);

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return all user groups:

Python:
Copy to clipboard
cloudinary.provisioning.account.user_groups()
Node.js:
Copy to clipboard
cloudinary.provisioning.account.user_groups()
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.userGroups();
cURL:
Copy to clipboard
curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
user_group(user_group_id, **options)
Node.js:
Copy to clipboard
user_group(string group_id, object options);
Java:
Copy to clipboard
userGroup(String groupId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.user_group("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.user_group("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.userGroup("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "id": "7f08f1f1fc910bf1f25274aef11d27",
  "name": "user_group_1"
}

Get user-group users

Return the users in the group with the specified ID.

Syntax

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

Python:
Copy to clipboard
user_group_users(user_group_id, **options)
Node.js:
Copy to clipboard
user_group_users(string group_id, object options);
Java:
Copy to clipboard
userGroupUsers(String groupId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.user_group_users("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.user_group_users("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.userGroupUsers("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27/users

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
create_user_group(name, **options)
Node.js:
Copy to clipboard
create_user_group(string name, object options);
Java:
Copy to clipboard
createUserGroup(String name, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.create_user_group("Designers)
Node.js:
Copy to clipboard
cloudinary.provisioning.account.create_user_group("Designers)
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.createUserGroup("Designers");
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Designers"
      }' \
  -X POST \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups

Sample response

Copy to clipboard
{
  "id": "7f08f1f1fc910bf1f25274aef11d27",
  "name": "Designers"
}

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

Python:
Copy to clipboard
add_user_to_group(user_group_id, user_id, **options)
Node.js:
Copy to clipboard
add_user_to_group(string group_id, string user_id, object options);
Java:
Copy to clipboard
addUserToGroup(String groupId, String userId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.add_user_to_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.add_user_to_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.addUserToGroup("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25");
cURL:
Copy to clipboard
curl \
  -X POST \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27/users/230df1d1fa913bf1f35e74a1f41e25

Sample response

Copy to clipboard
{
  "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

Python:
Copy to clipboard
update_user_group(group_id, name, **options)
Node.js:
Copy to clipboard
update_user_group(string group_id, string name, object options);
Java:
Copy to clipboard
updateUserGroup(String groupId, String name, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.update_user_group("7f08f1f1fc910bf1f25274aef11d27", "Designers")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.update_user_group("7f08f1f1fc910bf1f25274aef11d27", "Designers")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.updateUserGroup("7f08f1f1fc910bf1f25274aef11d27", "Designers");
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Designers"
      }' \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "id": "7f08f1f1fc910bf1f25274aef11d27",
  "name": "Designers"
}

Delete user group

Delete a user group with the specified ID.

Syntax

DELETE /accounts/:account_id/user_groups/:group_id

Python:
Copy to clipboard
delete_user_group(group_id, **options)
Node.js:
Copy to clipboard
delete_user_group(string group_id, object options);
Java:
Copy to clipboard
deleteUserGroup(String groupId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.delete_user_group("7f08f1f1fc910bf1f25274aef11d27")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.delete_user_group("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.deleteUserGroup("7f08f1f1fc910bf1f25274aef11d27");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27

Sample response

Copy to clipboard
{
  "message": "ok"
}

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

Python:
Copy to clipboard
remove_user_from_group(group_id, user_id, **options)
Node.js:
Copy to clipboard
remove_user_from_group(string group_id, string user_id, object options);
Java:
Copy to clipboard
removeUserFromGroup(String groupId, String userId, Map options);

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':

Python:
Copy to clipboard
cloudinary.provisioning.account.remove_user_from_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")
Node.js:
Copy to clipboard
cloudinary.provisioning.account.remove_user_from_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });
Java:
Copy to clipboard
account.removeUserFromGroup("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27/users/230df1d1fa913bf1f35e74a1f41e25

Sample response

Copy to clipboard
{
  "users": []
}

✔️ Feedback sent!