Programmable Media
Menu

Provisioning API (Classic)

Last updated: Feb-04-2025

New reference now available

This reference describes how to use the Provisioning API with our classic backend SDKs. You should use this reference only if you've already implemented Provisioning in your app using the classic backend SDKs, or if the language you need is not available via the new Provisioning SDKs.

For a more modern experience with OpenAPI generated documentation and SDKs, take a look at our new API reference.

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.

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

On this page:

Rate this page:

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:

GET https://api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts

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

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

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 product environments (sub_accounts):

JSON
{
  "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 product environments that have a name starting with 'prod':

Java
account.getSubAccounts(true, null, "prod");

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

  • Use the CLOUDINARY_ACCOUNT_URL environment variable, substituting the placeholders with your credentials:
export CLOUDINARY_ACCOUNT_URL=account://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@<ACCOUNT_ID>
  • Globally configure the Provisioning API using Account ID, Provisioning Key and Provisioning Secret defined separately:
cloudinary 2.x
const cloudinary = require('cloudinary').v2;

cloudinary.config({ 
  account_id: 'xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 
  provisioning_api_key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx', 
  provisioning_api_secret: 'xxxxxxxxxxx'
});

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

Error handling

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

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

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

JSON
{ "error": { "message": "User not found" } }

access_keys

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

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

Get access keys

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

Syntax

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

cloudinary 2.x
cloudinary.provisioning.account.access_keys(string sub_account_id, object options);

Optional parameters

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

Example

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

curl \
  -H "Content-Type: application/json" \

  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/<ACCOUNT_ID>/sub_accounts/<SUB_ACCOUNT_ID>/access_keys?sort_by=created_at&sort_order=asc

Sample response

JSON
{
  "access_keys": [
    {
      "name": "first_key",
      "api_key": "814814814814814",
      "api_secret": "QcsQcsQcsQcsQcsQcsQcsQcsQcs",
      "created_at": "2022-03-15T11:44:48Z",
      "updated_at": "2023-08-10T09:23:45Z",
      "enabled": true
    },
  ...
  ]
  "total": 10
}

Generate an access key

Generate a new access key.

Syntax

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

cloudinary 2.x
cloudinary.provisioning.account.generate_access_key(string sub_account_id, string name, object options);

Optional parameters

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

Example

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

\
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "main_key"
    }' \
  -X POST \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/<ACCOUNT_ID>/sub_accounts/<SUB_ACCOUNT_ID>/access_keys

Sample response

JSON
{
  "name": "main_key",
  "api_key": "418418418418418",
  "api_secret": "scQscQscQscQscQscQscQscQscQ",
  "created_at": "2023-09-10T09:23:45Z",
  "updated_at": "2023-09-10T09:23:45Z",
  "enabled": true
}

Update an access key

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

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

Syntax

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

cloudinary 2.x
cloudinary.provisioning.account.update_access_key(string sub_account_id, string api_key, boolean enabled, object options);

Optional parameters

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

Example

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

\
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "secondary_key", 
    "enabled": false
      }' \
  -X PUT \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/<ACCOUNT_ID>/sub_accounts/<SUB_ACCOUNT_ID>/access_keys/418418418418418

Sample response

JSON
{
  "name": "secondary_key",
  "api_key": "418418418418418",
  "api_secret": "scQscQscQscQscQscQscQscQscQ",
  "created_at": "2023-09-10T09:23:45Z",
  "updated_at": "2023-09-10T09:45:57Z",
  "enabled": false
}

Delete an access key by API key

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

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

Syntax

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

cloudinary 2.x
cloudinary.provisioning.account.delete_access_key(string sub_account_id, string api_key, object options);

Example

Delete the access key with API key 418418418418418 in the sub account with ID aksdvnklsR1234890:

\
  -H "Content-Type: application/json" \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/<ACCOUNT_ID>/sub_accounts/aksdvnklsR1234890/access_keys/418418418418418

Sample response

JSON
{
  "message": "ok"           
}

Delete an access key by name

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

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

Syntax

cloudinary 2.x
cloudinary.provisioning.account.delete_access_key(string sub_account_id, string name, object options);

Example

Delete the access key named secondary_key:

\
  -H "Content-Type: application/json" \
  -X DELETE \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/<ACCOUNT_ID>/sub_accounts/<SUB_ACCOUNT_ID>/access_keys?name=secondary_key

Sample response

JSON
{
  "message": "ok"           
}

sub_accounts (product environments)

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

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

cloudinary 2.x
cloudinary.provisioning.account.sub_accounts(boolean enabled, string[] ids, string prefix, object options);

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

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

JSON
{
  "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 product environment

Return the specified product environment.

Syntax

GET /accounts/:account_id/sub_accounts/:sub_account_id

cloudinary 2.x
cloudinary.provisioning.account.sub_account(string sub_account_id, object options);

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

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

Sample response

JSON
{
  "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 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

cloudinary 2.x
cloudinary.provisioning.account.create_sub_account(string name, string cloud_name, object custom_attributes, string base_account, object options);

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 cloud name comprised of 2-128 alphanumeric and hyphen characters, starting with a letter. Cloud names must be unique across all Cloudinary accounts.

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.
folder_mode String Sets the folder mode of the new product environment. Possible values: dynamic, fixed Default: dynamic
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':

curl \
  -H "Content-Type: application/json" \
  -d '{
        "name": "demo account"
      }' \
  -X POST \
  https://<PROVISIONING_KEY>:<PROVISIONING_SECRET>@api.cloudinary.com/v1_1/provisioning/accounts/16a8ff3b-736b-49a6-85c0-03b69d5a357b/sub_accounts

Sample response

JSON
{
  "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 product environment

Update the specified details of the product environment.

Syntax

PUT /accounts/:account_id/sub_accounts/:sub_account_id

cloudinary 2.x
cloudinary.provisioning.account.update_sub_account(string sub_account_id, string name, string cloud_name, object custom_attributes, boolean enabled, object options);

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 2-128 alphanumeric and hyphen characters, starting with a letter. Cloud names must be unique across all Cloudinary accounts.

Note: You can only change a cloud name (without special handling from customer support) for product environments with fewer than 1000 assets.
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':

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

JSON
{
  "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 product environment

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

Syntax

DELETE /accounts/:account_id/sub_accounts/:sub_account_id

cloudinary 2.x
cloudinary.provisioning.account.delete_sub_account(string sub_account_id, object options);

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

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

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.users(boolean pending, string[] ids, string prefix, string sub_account_id, object 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 begins with the specified case-insensitive string.
sub_account_id String Only returns users who have access to the specified account.
options Object See Configuration parameters.
last_login Boolean Specifies a date range for last login.
from String All last logins after this date, given in the format: yyyy-mm-dd
to String All last logins before this date, given in the format: yyyy-mm-dd
union_type String Whether to return users who last logged in within the specified date range (include), or those who didn't last log in within the range (exclude). Possible values: include, exclude Default: include

Example

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

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

JSON
{
  "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",
      "last_login": "2022-01-11T15:11:04Z",
      "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",
      "last_login": "2021-11-12T15:11:02Z",
      "all_sub_accounts": true
    }
  ]
}

Get user

Return the user with the specified ID.

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

Syntax

GET /accounts/:account_id/users/:user_id

cloudinary 2.x
cloudinary.provisioning.account.user(string user_id, object 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':

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

Sample response

JSON
{
  "id": "7f08f1f1fc910bf1f25274aef11d27",
  "name": "foobar",
  "role": "master_admin",
  "email": "email@domain.com",
  "pending": true,
  "enabled": true,
  "created_at": "2019-09-12T11:53:57Z",
  "last_login": "2022-01-11T15:11:04Z",
  "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

cloudinary 2.x
cloudinary.provisioning.account.create_user(string name, string email, string role, string[] sub_account_ids, object 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_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':

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

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.update_user(string user_id, string name, string email, string role, string[] sub_account_ids, object 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 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':

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

JSON
{
  "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.

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

Syntax

DELETE /accounts/:account_id/users/:user_id

cloudinary 2.x
cloudinary.provisioning.account.delete_user(string user_id, object 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':

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

Sample response

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.user_groups(object options);

Optional parameters

Parameter Type Description
options Object See Configuration parameters.

Example

Return all user groups:

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

Sample response

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.user_group(string group_id, object 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':

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

Sample response

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.user_group_users(string group_id, object 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':

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

Sample response

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.create_user_group(string name, object 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':

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

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.add_user_to_group(string group_id, string user_id, object 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':

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

JSON
{
  "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

cloudinary 2.x
cloudinary.provisioning.account.update_user_group(string group_id, string name, object 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':

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

JSON
{
  "id": "7f08f1f1fc910bf1f25274aef11d27",
  "name": "Designers"
}

Delete user group

Delete a user group with the specified ID.

Syntax

DELETE /accounts/:account_id/user_groups/:group_id

cloudinary 2.x
cloudinary.provisioning.account.delete_user_group(string group_id, object 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':

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

JSON
{
  "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

cloudinary 2.x
remove_user_from_group(string group_id, string user_id, object 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':

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

JSON
{
  "users": []
}

✔️ Feedback sent!