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.

On this page:

Overview
Sub-accounts
Users
User groups

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
Error handling
Pagination

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

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:

{ "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 Node.js Java All

Python:

sub_accounts(enabled=None, ids=None, prefix=None, **options)

Node.js:

sub_accounts(boolean enabled, string[] ids, string prefix, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.sub_accounts(True, prefix = "product")

Node.js:

cloudinary.provisioning.account.sub_accounts(true, null, "product")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.subAccounts(true, null, "product");

cURL:

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

{
  "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 Node.js Java All

Python:

sub_account(sub_account_id, **options)

Node.js:

sub_accounts(string sub_account_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.sub_account("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.sub_account("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.subAccount("7f08f1f1fc910bf1f25274aef11d27");

cURL:

curl \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts/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

Python Node.js Java All

Python:

create_sub_account(name, cloud_name=None, custom_attributes=None, enabled=None, base_account=None, **options)

Node.js:

create_sub_account(string name, string cloud_name, object custom_attributes, boolean enabled, string base_account, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.create_sub_account("demo account", enabled = False)

Node.js:

cloudinary.provisioning.account.create_sub_account("demo account", null, null, false)
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.createSubAccount("demo account", null, ObjectUtils.emptyMap(), false, null);

cURL:

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

{
  "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 Node.js Java All

Python:

update_sub_account(sub_account_id, name=None, cloud_name=None, custom_attributes=None, enabled=None, base_account=None, **options)

Node.js:

update_sub_account(string sub_account_id, string name, string cloud_name, object custom_attributes, boolean enabled, object options);

Java:

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 Node.js Java cURL All

Python:

update_sub_account("7f08f1f1fc910bf1f25274aef11d27", enabled = False)

Node.js:

cloudinary.provisioning.account.update_sub_account("7f08f1f1fc910bf1f25274aef11d27", null, null, {}, false)
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.updateSubAccount("7f08f1f1fc910bf1f25274aef11d27", null, null, {ObjectUtils.emptyMap()}, false);

cURL:

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

{
  "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 Node.js Java All

Python:

delete_sub_account(sub_account_id, **options)

Node.js:

delete_sub_account(string sub_account_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.delete_sub_account("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.delete_sub_account("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.deleteSubAccount("7f08f1f1fc910bf1f25274aef11d27");

cURL:

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

{
  "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 Node.js Java All

Python:

users(user_ids=None, sub_account_id=None, pending=None, prefix=None, **options)

Node.js:

users(boolean pending, string[]] ids, string prefix, string sub_account_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.users(prefix = "john")

Node.js:

cloudinary.provisioning.account.users(null, null, "john")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.Users(null, null, "john", null);

cURL:

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

{
  "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 Node.js Java All

Python:

user(user_id, **options)

Node.js:

user(string user_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.user("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.user("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.user("7f08f1f1fc910bf1f25274aef11d27");

cURL:

curl \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users/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

Python Node.js Java All

Python:

create_user(name, email, role, sub_account_ids=None, **options)

Node.js:

create_user(string name, string email, string role, string[] sub_accounts_ids, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.create_user("John", "john@example.com", "technical_admin")

Node.js:

cloudinary.provisioning.account.create_user("John", "john@example.com", "technical_admin")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.createUser("John", "john@example.com", "technical_admin", null);

cURL:

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

{
  "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 Node.js Java All

Python:

update_user(user_id, name=None, email=None, role=None, sub_account_ids=None, **options)

Node.js:

update_user(string user_id, string name, string email, string role, string[] sub_accounts_ids, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.update_user("7f08f1f1fc910bf1f25274aef11d27", role = "admin")

Node.js:

cloudinary.provisioning.account.update_user("7f08f1f1fc910bf1f25274aef11d27", null, null, "admin")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.updateUser("7f08f1f1fc910bf1f25274aef11d27", null, null, "admin", null);

cURL:

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

{
  "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 Node.js Java All

Python:

delete_user(user_id, **options)

Node.js:

delete_user(string user_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.delete_user("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.delete_user("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.deleteUser("7f08f1f1fc910bf1f25274aef11d27");

cURL:

curl \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/users/7f08f1f1fc910bf1f25274aef11d27

Sample response

{
  "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 Node.js Java All

Python:

user_groups(**options)

Node.js:

user_groups(object options);

Java:

userGroups(Map options);

Optional parameters

Parameter	Type	Description
options	Object	See Configuration parameters.

Example

Return all user groups:

Python Node.js Java cURL All

Python:

cloudinary.provisioning.account.user_groups()

Node.js:

cloudinary.provisioning.account.user_groups()
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.userGroups();

cURL:

curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/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

Python Node.js Java All

Python:

user_group(user_group_id, **options)

Node.js:

user_group(string group_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.user_group("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.user_group("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.userGroup("7f08f1f1fc910bf1f25274aef11d27");

cURL:

curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27

Sample response

{
  "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 Node.js Java All

Python:

user_group_users(user_group_id, **options)

Node.js:

user_group_users(string group_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.user_group_users("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.user_group_users("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.userGroupUsers("7f08f1f1fc910bf1f25274aef11d27");

cURL:

curl https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/user_groups/7f08f1f1fc910bf1f25274aef11d27/users

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

Python Node.js Java All

Python:

create_user_group(name, **options)

Node.js:

create_user_group(string name, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.create_user_group("Designers)

Node.js:

cloudinary.provisioning.account.create_user_group("Designers)
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.createUserGroup("Designers");

cURL:

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

{
  "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 Node.js Java All

Python:

add_user_to_group(user_group_id, user_id, **options)

Node.js:

add_user_to_group(string group_id, string user_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.add_user_to_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")

Node.js:

cloudinary.provisioning.account.add_user_to_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.addUserToGroup("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25");

cURL:

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

{
  "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 Node.js Java All

Python:

update_user_group(group_id, name, **options)

Node.js:

update_user_group(string group_id, string name, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.update_user_group("7f08f1f1fc910bf1f25274aef11d27", "Designers")

Node.js:

cloudinary.provisioning.account.update_user_group("7f08f1f1fc910bf1f25274aef11d27", "Designers")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.updateUserGroup("7f08f1f1fc910bf1f25274aef11d27", "Designers");

cURL:

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

{
  "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 Node.js Java All

Python:

delete_user_group(group_id, **options)

Node.js:

delete_user_group(string group_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.delete_user_group("7f08f1f1fc910bf1f25274aef11d27")

Node.js:

cloudinary.provisioning.account.delete_user_group("7f08f1f1fc910bf1f25274aef11d27")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.deleteUserGroup("7f08f1f1fc910bf1f25274aef11d27");

cURL:

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

{
  "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 Node.js Java All

Python:

remove_user_from_group(group_id, user_id, **options)

Node.js:

remove_user_from_group(string group_id, string user_id, object options);

Java:

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 Node.js Java cURL All

Python:

cloudinary.provisioning.account.remove_user_from_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")

Node.js:

cloudinary.provisioning.account.remove_user_from_group("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25")
  .then((response) => { console.log(response); })
  .catch((err) => { console.log(err); });

Java:

account.removeUserFromGroup("7f08f1f1fc910bf1f25274aef11d27", "230df1d1fa913bf1f35e74a1f41e25");

cURL:

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

{
  "users": []
}

✔️ Feedback sent!

✖️

Error

Unfortunately there's been an error sending your feedback.

Is this page helpful?