Cloudinary Account Provisioning JavaScript SDK

Developer-friendly & type-safe TypeScript SDK specifically catered to leverage the Cloudinary Account Provisioning API.

Summary

Cloudinary Account Provisioning API: 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.

The API uses Basic Authentication over HTTPS. Your Account API Key and Account API Secret (previously referred to as Provisioning API keys) are used for the authentication. These credentials (as well as your ACCOUNT_ID) are located in the Cloudinary Console under Settings > Account API Keys.

The Provisioning API has dedicated SDKs for the following languages:

Useful links:

Provisioning API reference (Classic) (includes SDKs for additional languages)

Accounts with Permissions API access can assign roles, made up of system policies, to control what principals (users, groups, and API keys) can do across the Cloudinary account and product environments. For more information about Cloudinary roles and permissions, see the Role-based permissions guide.

Permissions API access is available upon request for accounts on an Enterprise plan.

The API uses Basic Authentication over HTTPS. Your Account API Key and Account API Secret (previously referred to as Provisioning API keys) are used for the authentication. These credentials (as well as your ACCOUNT_ID) are located in the Cloudinary Console under Settings > Account API Keys.

Important:

Cloudinary's Roles and Permissions Management is now available as a Beta. This is an early stage release, and while it's functional and ready for real-world testing, it's subject to change as we continue refining the experience based on what we learn, including your feedback. During the Beta period, core functionality is considered stable, though some APIs, scopes, or response formats may evolve.

How you can help:

Use Roles and Permissions Management in real projects, prototypes, or tests.
Share feedback, issues, or ideas with our support team.

Thank you for exploring this early release and helping us shape these tools to best meet your needs.

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @cloudinary/account-provisioning

PNPM

pnpm add @cloudinary/account-provisioning

Bun

bun add @cloudinary/account-provisioning

Yarn

yarn add @cloudinary/account-provisioning

Note

This package is published with CommonJS and ES Modules (ESM) support.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

Configuration

Environment Variables

The SDK loads credentials and configuration automatically from environment variables. The simplest way to configure the SDK is to set the CLOUDINARY_ACCOUNT_URL environment variable:

export CLOUDINARY_ACCOUNT_URL=account://<PROVISIONING_API_KEY>:<PROVISIONING_API_SECRET>@<ACCOUNT_ID>

This single URL provides all three required values. You can find these credentials in the Cloudinary Console under Settings > Account API Keys.

Alternatively, you can set each value individually:

Environment Variable	Description
`CLOUDINARY_ACCOUNT_URL`	Account URL (recommended — provides all values below)
`CLOUDINARY_PROVISIONING_API_KEY`	Account API Key
`CLOUDINARY_PROVISIONING_API_SECRET`	Account API Secret
`CLOUDINARY_ACCOUNT_ID`	Account ID
`CLOUDINARY_DEBUG`	Set to `true` to enable HTTP debug logging

Individual environment variables take precedence over values parsed from CLOUDINARY_ACCOUNT_URL.

Usage with Environment Variables

When environment variables are set, no constructor arguments are needed:

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

const result = await cldProvisioning.productEnvironments.list({});
console.log(result);

Explicit Configuration

You can also pass credentials directly:

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning({
  security: {
    provisioningApiKey: "YOUR_API_KEY",
    provisioningApiSecret: "YOUR_API_SECRET",
  },
  accountId: "YOUR_ACCOUNT_ID",
});

SDK Example Usage

Example

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  });

  console.log(result);
}

run();

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme	Environment Variable
`provisioningApiKey` `provisioningApiSecret`	http	Custom HTTP	`CLOUDINARY_PROVISIONING_API_KEY` `CLOUDINARY_PROVISIONING_API_SECRET`

You can set the security parameters through the security optional parameter when initializing the SDK client instance. For example:

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  });

  console.log(result);
}

run();

Available Resources and Operations

Available methods

ProductEnvironments

list - Get product environments
create - Create product environment
get - Get product environment
update - Update product environment
delete - Delete product environment

AccessKeys

list - Get access keys
generate - Generate an access key
deleteByName - Delete access key by name
update - Update an access key
delete - Delete access key

Users

list - Get users
create - Create user
get - Get user
update - Update user
delete - Delete user
getGroups - Get user groups
listSubAccounts - Get user sub-accounts

UserGroups

list - Get User Groups
create - Create User Group
get - Get User Group
update - Update User Group
delete - Delete User Group
listUsers - Get Users in User Group
addUser - Add User to User Group
removeUser - Remove User from User Group

BillingUsage

get - Get billing usage information

SystemPolicies

list - Get system policies

Roles

list - Get roles
create - Create custom role
get - Get role
update - Update custom role
delete - Delete custom role
listPrincipals - Get a role's principals
updatePrincipals - Assign principals to a role

CustomPolicies

list - Get custom policies
create - Create custom policy
get - Get custom policy
update - Update custom policy
delete - Delete custom policy

EffectivePolicies

list - Get effective policies

Principals

listRoles - Get a principal's roles
updateRoles - Assign roles to a principal
inspect - Inspect
inspectMultiple - Inspect multiple

Public

getCatalog - Get system roles and policies catalog
validatePolicy - Validate a Cedar policy
getSchema - Get Cedar schema

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

Available standalone functions

accessKeysDelete - Delete access key
accessKeysDeleteByName - Delete access key by name
accessKeysGenerate - Generate an access key
accessKeysList - Get access keys
accessKeysUpdate - Update an access key
billingUsageGet - Get billing usage information
customPoliciesCreate - Create custom policy
customPoliciesDelete - Delete custom policy
customPoliciesGet - Get custom policy
customPoliciesList - Get custom policies
customPoliciesUpdate - Update custom policy
effectivePoliciesList - Get effective policies
principalsInspect - Inspect
principalsInspectMultiple - Inspect multiple
principalsListRoles - Get a principal's roles
principalsUpdateRoles - Assign roles to a principal
productEnvironmentsCreate - Create product environment
productEnvironmentsDelete - Delete product environment
productEnvironmentsGet - Get product environment
productEnvironmentsList - Get product environments
productEnvironmentsUpdate - Update product environment
publicGetCatalog - Get system roles and policies catalog
publicGetSchema - Get Cedar schema
publicValidatePolicy - Validate a Cedar policy
rolesCreate - Create custom role
rolesDelete - Delete custom role
rolesGet - Get role
rolesList - Get roles
rolesListPrincipals - Get a role's principals
rolesUpdate - Update custom role
rolesUpdatePrincipals - Assign principals to a role
systemPoliciesList - Get system policies
userGroupsAddUser - Add User to User Group
userGroupsCreate - Create User Group
userGroupsDelete - Delete User Group
userGroupsGet - Get User Group
userGroupsList - Get User Groups
userGroupsListUsers - Get Users in User Group
userGroupsRemoveUser - Remove User from User Group
userGroupsUpdate - Update User Group
usersCreate - Create user
usersDelete - Delete user
usersGet - Get user
usersGetGroups - Get user groups
usersList - Get users
usersListSubAccounts - Get user sub-accounts
usersUpdate - Update user

Global Parameters

A parameter is configured globally. This parameter may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, This global value will be used as the default on the operations that use it. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set account_id to "<id>" at SDK initialization and then you do not have to pass the same value on calls to operations like list. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

Available Globals

The following global parameter is available. Global parameters can also be set via environment variable.

Name	Type	Description	Environment
accountId	string	Account ID	CLOUDINARY_ACCOUNT_ID

Example

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  });

  console.log(result);
}

run();

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  });

  console.log(result);
}

run();

Error Handling

CldProvisioningError is the base class for all HTTP error responses. It has the following properties:

Property	Type	Description
`error.message`	`string`	Error message
`error.statusCode`	`number`	HTTP response status code eg `404`
`error.headers`	`Headers`	HTTP response headers
`error.body`	`string`	HTTP body. Can be empty string if no body is returned.
`error.rawResponse`	`Response`	Raw HTTP response
`error.data$`		Optional. Some errors may contain structured data. See Error Classes.

Example

import * as models from "@cloudinary/account-provisioning";
import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  try {
    const result = await cldProvisioning.productEnvironments.list({
      enabled: true,
      prefix: "product",
    });

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof models.CldProvisioningError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof models.ErrorResponse) {
        console.log(error.data$.error); // models.ErrorT
      }
    }
  }
}

run();

Error Classes

Primary error:

CldProvisioningError: The base class for HTTP error responses.

Less common errors (8)

Network errors:

ConnectionError: HTTP client was unable to make a request to a server.
RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.
RequestAbortedError: HTTP request was aborted by the client.
InvalidRequestError: Any input used to create a request is invalid.
UnexpectedClientError: Unrecognised or unexpected error.

Inherit from CldProvisioningError:

ErrorResponse: Bad request. Applicable to 26 of 47 methods.*
PermissionsErrorResponse: Applicable to 18 of 47 methods.*
ResponseValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. See error.rawValue for the raw value and error.pretty() for a nicely formatted multi-line string.

* Check the method documentation to see if the error is applicable.

Server Selection

Select Server by Index

You can override the default server globally by passing a server index to the serverIdx: number optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:

#	Server	Variables	Description
0	`https://{region}.cloudinary.com`	`region`	Regional API endpoints for optimal performance.
1	`https://{host}`	`host`	Custom domains for enterprise deployments.

If the selected server has variables, you may override its default values through the additional parameters made available in the SDK constructor:

Variable	Parameter	Supported Values	Default	Description
`region`	`region: models.ServerRegion`	- `"api"` - `"api-eu"` - `"api-ap"`	`"api"`	Regional endpoint selection
`host`	`host: string`	string	`"api.cloudinary.com"`	API host domain.

Example

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  });

  console.log(result);
}

run();

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the serverURL: string optional parameter when initializing the SDK client instance. For example:

import { CldProvisioning } from "@cloudinary/account-provisioning";

const cldProvisioning = new CldProvisioning();

async function run() {
  const result = await cldProvisioning.productEnvironments.list({
    enabled: true,
    prefix: "product",
  });

  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to:

route requests through a proxy server using undici's ProxyAgent
use the "beforeRequest" hook to add a custom header and a timeout to requests
use the "requestError" hook to log errors

import { CldProvisioning } from "@cloudinary/account-provisioning";
import { ProxyAgent } from "undici";
import { HTTPClient } from "@cloudinary/account-provisioning/lib/http";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");

const httpClient = new HTTPClient({
  // 'fetcher' takes a function that has the same signature as native 'fetch'.
  fetcher: (input, init) =>
    // 'dispatcher' is specific to undici and not part of the standard Fetch API.
    fetch(input, { ...init, dispatcher } as RequestInit),
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new CldProvisioning({ httpClient: httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

Warning

Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { CldProvisioning } from "@cloudinary/account-provisioning";

const sdk = new CldProvisioning({ debugLogger: console });

You can also enable a default debug logger by setting an environment variable CLOUDINARY_DEBUG to true.

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.cursor/rules		.cursor/rules
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.speakeasy		.speakeasy
docs		docs
examples		examples
scripts		scripts
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.oxlintrc.json		.oxlintrc.json
CONTRIBUTING.md		CONTRIBUTING.md
FUNCTIONS.md		FUNCTIONS.md
LICENSE.md		LICENSE.md
README.md		README.md
RELEASES.md		RELEASES.md
RUNTIMES.md		RUNTIMES.md
USAGE.md		USAGE.md
jsr.json		jsr.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Cloudinary Account Provisioning JavaScript SDK

Summary

Table of Contents

SDK Installation

NPM

PNPM

Bun

Yarn

Requirements

Configuration

Environment Variables

Usage with Environment Variables

Explicit Configuration

SDK Example Usage

Example

Authentication

Per-Client Security Schemes

Available Resources and Operations

Standalone functions

Global Parameters

Available Globals

Example

Retries

Error Handling

Example

Error Classes

Server Selection

Select Server by Index

Example

Override Server URL Per-Client

Custom HTTP Client

Debugging

Development

Maturity

Contributions

SDK Created by Speakeasy

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Uh oh!

Uh oh!

Languages