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:

• JavaScript
• PHP
• Java

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.

Table of Contents

• Cloudinary Account Provisioning JavaScript SDK
  • SDK Installation
  • Requirements
  • Configuration
  • SDK Example Usage
  • Authentication
  • Available Resources and Operations
  • Standalone functions
  • Global Parameters
  • Retries
  • Error Handling
  • Server Selection
  • Custom HTTP Client
  • Debugging
• Development
  • Maturity
  • Contributions

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 | | ------------------------------------------------ | ---- | ----------- | -------------------------------------------------------------------------- | | provisioningApiKeyprovisioningApiSecret | http | Custom HTTP | CLOUDINARY_PROVISIONING_API_KEYCLOUDINARY_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

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.

• 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.

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.

SDK Created by Speakeasy