Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

v2.0.1OAS 3.0.3

Cloudinary Account Permissions API

Download OpenAPI Document

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. It isn't available on the Free plan or on self-serve paid plans.

The API uses Basic Authentication over HTTPS. Your Account Management Key and Account Management Secret (previously referred to as Account API Keys and 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 Management Keys.

The Provisioning and Permissions APIs share one set of SDKs, and each SDK covers both APIs:

Useful links:

System Policies

View all system policies predefined by Cloudinary, which can be associated with roles.

Get system policies

Retrieve all system-defined permission policies. Optionally filter the results by scope_type (account or product environment) and/or permission_type (global or content-specific).

Note: If scope_type isn't specified as prodenv, the account-level policies will be returned.

Path parameters

  • account_id stringRequired

    Account ID

Query parameters

  • permission_type string

    Specifies whether to retrieve roles whose permissions apply globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

    example "global"
    enum "global" "content"
  • scope_type string

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"

Responses

200 Successful operation
application/json
SystemPoliciesResponse
  • data SystemPolicyResponseData[]

    An array of system policies.

    ShowHide child attributes of data
    Items SystemPolicyResponseData
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • permission_type string

      Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • category string

      The category of the policy.

      example "Management"
    • sub_category string

      The sub-category of the policy.

      example "General operations"
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
  • next_cursor string

    When a request has more results to return, the next_cursor value is returned as part of the response. You can then specify this value as the cursor parameter of a following request.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/policies/system
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/system' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": [
    {
      "id": "cld::policy::global::assets::moderate",
      "name": "Moderate all assets",
      "description": "Approve and reject all assets in moderation. To perform these actions from the Moderation page, pair this permission with 'Access the Moderation page'. To view assets on the page, pair it with the 'View all folders and assets' global permission.",
      "scope_type": "prodenv",
      "permission_type": "global",
      "policy_statement": "permit(principal, action == Cloudinary::Action::\"moderate\", resource is Cloudinary::Asset);",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "cld::policy::content::folder::view_download",
      "name": "View all assets",
      "description": "View all assets in the folder and its nested subfolders.",
      "scope_type": "prodenv",
      "permission_type": "content",
      "policy_statement": "permit(principal, action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder) when { resource.ancestor_ids.contains(\"<folder_id>\") };\npermit(principal, action == Cloudinary::Action::\"read\", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains(\"<folder_id>\") };\n",
      "policy_parameters": [
        "folder_id"
      ],
      "created_at": 1719475216,
      "updated_at": 1719475216
    }
  ],
  "next_cursor": "3"
}

Roles

All roles include one or more predefined system policies, and can be applied to principals to enforce these policies.

You can manage custom roles, where you select the system policies.

You can view system roles, which contain a fixed set of system policies and are provided by Cloudinary.

Get roles

Retrieve all system and custom roles of a specific permission_type (global or content-specific). Optionally filter by scope_type, management_type, and policy_parameters.

Path parameters

  • account_id stringRequired

    Account ID

Query parameters

  • scope_type string

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • permission_type stringRequired

    Specifies whether to retrieve roles whose permissions apply globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

    example "global"
    enum "global" "content"
  • management_type string

    Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

    example "system"
    enum "system" "custom"
  • policy_parameters any

    For roles with permission_type set to content, this defines the type of content the role's policies apply to:

    • The content type can be: folder_id or collection_id.
    • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).

Responses

200 Successful operation
application/json
RolesResponse
  • data RoleResponseData[]

    An array of roles.

    ShowHide child attributes of data
    Items RoleResponseData
    • id stringRequired

      The unique identifier of the role.

      example "cld::role::prodenv::master_admin"
    • name stringRequired

      The name of the role.

      example "Master admin"
    • description stringnullable

      A short description of the role.

      example "Full access."
    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • created_at integerRequired

      The permission policy creation timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      The permission policy last updated timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/roles
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles?permission_type=global' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": [
    {
      "id": "cld::role::account::master_admin",
      "name": "Master Admin",
      "description": "Manage all account-level settings and features.",
      "management_type": "system",
      "permission_type": "global",
      "scope_type": "account",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "cld::role::account::admin",
      "name": "Admin",
      "description": "Manage roles, users, and groups, and access Cloudinary products.",
      "management_type": "system",
      "permission_type": "global",
      "scope_type": "account",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "custom::role::account::admin_assist",
      "name": "Admin",
      "description": "View roles, users and groups, and account-level reports.",
      "management_type": "custom",
      "permission_type": "global",
      "scope_type": "account",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "cld::role::prodenv::ml_user",
      "name": "Media Library User",
      "description": "Access specific folders and collections according to assigned permissions.",
      "management_type": "system",
      "permission_type": "global",
      "scope_type": "prodenv",
      "created_at": 1719475216,
      "updated_at": 1719475216
    }
  ]
}

Create custom role

Create a new custom role.

Path parameters

  • account_id stringRequired

    Account ID

Body Required application/json

Role details.

CreateRole
  • id string

    The unique identifier for the role.

    • When creating a new role: If not provided, the system will auto-generate the ID.
    • When updating a role: Specify the ID of the role you want to update.
    example "upload_manager_12334565"
  • permission_type stringRequired

    Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr"). Note: This attrubute is immutable.

    • global
    • content
    example "global"
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • name stringRequired

    The name of the role.

    example "Upload manager"
  • description stringnullable

    A short description of the role.

    example "Responsible for managing upload presets and uploading new assets."
  • system_policy_ids string[]

    A list of system permission policy IDs to be included in the role.

    Tip: Get the list of all available predefined policies using the Get system policies method.

Responses

201 Role created successfully
application/json
RoleResponse
  • data object
    ShowHide child attributes of data
    • policies SystemPolicyResponseData[]
      ShowHide child attributes of policies
      Items SystemPolicyResponseData
      • id stringRequired

        The unique identifier of the policy.

        example "12jf789l12hwiuencl7aaqey"
      • name stringRequired

        The name of the policy

        example "Read access to Clothing folder"
      • description stringnullable

        A short description of the policy.

        example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
      • scope_type stringRequired

        Specifies where the role/policy is applied, either at the account level or within product environments.

        example "prodenv"
        enum "account" "prodenv"
      • permission_type string

        Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

        - global
        
        - content
        
        example "global"
      • policy_statement stringRequired

        A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

        example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
      • policy_parameters string[]

        For roles with permission_type set to content, this defines the type of content the role's policies apply to:

        • The content type can be: folder_id or collection_id.
        • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        example ["folder_id"]
      • category string

        The category of the policy.

        example "Management"
      • sub_category string

        The sub-category of the policy.

        example "General operations"
      • created_at integerRequired

        Creation time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
      • updated_at integerRequired

        Last update time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
    • id stringRequired

      The unique identifier of the role.

      example "cld::role::prodenv::master_admin"
    • name stringRequired

      The name of the role.

      example "Master admin"
    • description stringnullable

      A short description of the role.

      example "Full access."
    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • created_at integerRequired

      The permission policy creation timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      The permission policy last updated timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
400 Missing fields or invalid field
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

409 Already exists
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

POST/v2/accounts/{account_id}/permissions/roles
curl -X POST 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "upload_manager_12334565",
  "permission_type": "global",
  "scope_type": "prodenv",
  "name": "Upload manager",
  "description": "Responsible for managing uploads and uploading new assets.",
  "system_policy_ids": [
    "cld::policy::global::upload_presets::manage",
    "cld::policy::global::folder_and_asset_management::create_asset"
  ]
}'
Response
{
  "data": {
    "policies": [
      {
        "id": "cld::policy::global::upload_presets::manage",
        "name": "Manage upload settings",
        "description": "View, create, modify, or delete upload settings, such as upload presets, upload mappings, and upload defaults.",
        "scope_type": "prodenv",
        "permission_type": "global",
        "policy_statement": "permit (principal, action in [Cloudinary::Action::\"create\", Cloudinary::Action::\"read\", Cloudinary::Action::\"update\", Cloudinary::Action::\"delete\"], resource is Cloudinary::UploadPreset);",
        "category": "Settings",
        "sub_category": "Upload Settings",
        "created_at": 1719475215,
        "updated_at": 1719475215
      },
      {
        "id": "cld::policy::global::folder_and_asset_management::create_asset",
        "name": "Upload assets",
        "description": "Upload assets to any folder, including the root, without requiring specific folder permissions. Includes the option to select an upload preset and apply tags and metadata. ",
        "scope_type": "prodenv",
        "permission_type": "global",
        "policy_statement": "permit ( principal, action in [Cloudinary::Action::\"create\", Cloudinary::Action::\"read\"], resource is Cloudinary::Asset) permit ( principal, action in [Cloudinary::Action::\"create\", Cloudinary::Action::\"read\"], resource is Cloudinary::Folder)",
        "category": "Management",
        "sub_category": "Folder and asset management",
        "created_at": 1719475215,
        "updated_at": 1719475215
      }
    ],
    "id": "upload_manager_12334565",
    "name": "Upload manager",
    "description": "Responsible for managing upload presets and uploading new assets.",
    "management_type": "custom",
    "permission_type": "global",
    "scope_type": "prodenv",
    "created_at": 1719475216,
    "updated_at": 1719475216
  }
}

Get role

Get a specific system or custom role.

Path parameters

  • account_id stringRequired

    Account ID

  • role_id stringRequired

    A unique identifier for the role.

Query parameters

  • folder_id string
    • In the Get role endpoint, the specified folder_id is included in the policy_statement parameter of the response. If no folder_id is specified, the policy_statement shows a placeholder for the folder_id where relevant.
    • In the Get a principal's roles, Get a role's principals, and Inspect endpoints, the results are filtered by the specified folder_id. Only roles or principals with policy_statement parameters associated with that folder_id are returned.
  • asset_id string

    Not currently supported.

  • collection_id string
    • In the Get role endpoint, the specified collection_id is included in the policy_statement parameter of the response. If no collection_id is specified, the policy_statement shows a placeholder for the collection_id where relevant.
    • In the Get a principal's roles and Get a role's principals endpoints, the results are filtered by the specified collection_id. Only roles or principals with policy_statement parameters associated with that collection_id are returned.
  • param_key string[]

    The type of content instance the role applies to, either folder_id or collection_id. Use together with param_value to retrieve role assignments as they apply to a specific instance.

    example ["folder_id"]
  • param_value string[]

    The ID of the content instance (for example, a specific folder or collection). Use together with param_key to retrieve roles as they apply to a specific instance.

    example ["asdfjkl12347890"]

Responses

200 Successful operation
application/json
RoleResponse
  • data object
    ShowHide child attributes of data
    • policies SystemPolicyResponseData[]
      ShowHide child attributes of policies
      Items SystemPolicyResponseData
      • id stringRequired

        The unique identifier of the policy.

        example "12jf789l12hwiuencl7aaqey"
      • name stringRequired

        The name of the policy

        example "Read access to Clothing folder"
      • description stringnullable

        A short description of the policy.

        example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
      • scope_type stringRequired

        Specifies where the role/policy is applied, either at the account level or within product environments.

        example "prodenv"
        enum "account" "prodenv"
      • permission_type string

        Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

        - global
        
        - content
        
        example "global"
      • policy_statement stringRequired

        A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

        example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
      • policy_parameters string[]

        For roles with permission_type set to content, this defines the type of content the role's policies apply to:

        • The content type can be: folder_id or collection_id.
        • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        example ["folder_id"]
      • category string

        The category of the policy.

        example "Management"
      • sub_category string

        The sub-category of the policy.

        example "General operations"
      • created_at integerRequired

        Creation time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
      • updated_at integerRequired

        Last update time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
    • id stringRequired

      The unique identifier of the role.

      example "cld::role::prodenv::master_admin"
    • name stringRequired

      The name of the role.

      example "Master admin"
    • description stringnullable

      A short description of the role.

      example "Full access."
    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • created_at integerRequired

      The permission policy creation timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      The permission policy last updated timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/roles/{role_id}
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles/{role_id}' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": {
    "policies": [
      {
        "id": "cld::policy::global::upload_presets::manage",
        "name": "Manage upload settings",
        "description": "View, create, modify, or delete upload settings, such as upload presets, upload mappings, and upload defaults.",
        "scope_type": "prodenv",
        "permission_type": "global",
        "policy_statement": "permit(principal, action, resource is Cloudinary::UploadPreset);\npermit(principal, action, resource is Cloudinary::UploadMapping);\npermit(principal, action == Cloudinary::Action::\"update_settings\", resource is Cloudinary::ProductEnvironment);\npermit(principal, action, resource == Cloudinary::Feature::\"cld::global::upload_settings::manage\");\npermit(principal, action, resource == Cloudinary::Feature::\"cld::global::upload_settings::access\");\n",
        "category": "Settings",
        "sub_category": "Upload Settings",
        "created_at": 1719475215,
        "updated_at": 1719475215
      },
      {
        "id": "cld::policy::global::folder_and_asset_management::create_asset",
        "name": "Upload assets",
        "description": "Upload assets to any folder, including the root, without requiring specific folder permissions. Includes the option to select an upload preset and apply tags and metadata.",
        "scope_type": "prodenv",
        "permission_type": "global",
        "policy_statement": "permit(principal, action in [Cloudinary::Action::\"create\"], resource is Cloudinary::Asset);",
        "category": "Management",
        "sub_category": "Folder and asset management",
        "created_at": 1719475215,
        "updated_at": 1719475215
      }
    ],
    "id": "upload_manager_12334565",
    "name": "Upload manager",
    "description": "Responsible for managing upload settings and uploading new assets.",
    "management_type": "custom",
    "permission_type": "global",
    "scope_type": "prodenv",
    "created_at": 1719475216,
    "updated_at": 1719475216
  }
}

Update custom role

Update a specific custom role by providing all relevant details, including those you want to keep as-is.

Note: Updating a role with a name that already exists will trigger a 409 error.

Path parameters

  • account_id stringRequired

    Account ID

  • role_id stringRequired

    A unique identifier for the role.

Body Required application/json

Role details

Role
  • name stringRequired

    The name of the role.

    example "Upload manager"
  • description stringnullable

    A short description of the role.

    example "Responsible for managing upload presets and uploading new assets."
  • system_policy_ids string[]

    A list of system permission policy IDs to be included in the role.

    Tip: Get the list of all available predefined policies using the Get system policies method.

Responses

200 Role updated successfully
application/json
RoleResponse
  • data object
    ShowHide child attributes of data
    • policies SystemPolicyResponseData[]
      ShowHide child attributes of policies
      Items SystemPolicyResponseData
      • id stringRequired

        The unique identifier of the policy.

        example "12jf789l12hwiuencl7aaqey"
      • name stringRequired

        The name of the policy

        example "Read access to Clothing folder"
      • description stringnullable

        A short description of the policy.

        example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
      • scope_type stringRequired

        Specifies where the role/policy is applied, either at the account level or within product environments.

        example "prodenv"
        enum "account" "prodenv"
      • permission_type string

        Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

        - global
        
        - content
        
        example "global"
      • policy_statement stringRequired

        A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

        example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
      • policy_parameters string[]

        For roles with permission_type set to content, this defines the type of content the role's policies apply to:

        • The content type can be: folder_id or collection_id.
        • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        example ["folder_id"]
      • category string

        The category of the policy.

        example "Management"
      • sub_category string

        The sub-category of the policy.

        example "General operations"
      • created_at integerRequired

        Creation time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
      • updated_at integerRequired

        Last update time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
    • id stringRequired

      The unique identifier of the role.

      example "cld::role::prodenv::master_admin"
    • name stringRequired

      The name of the role.

      example "Master admin"
    • description stringnullable

      A short description of the role.

      example "Full access."
    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • created_at integerRequired

      The permission policy creation timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      The permission policy last updated timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
400 Missing fields, invalid field
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

409 Conflict
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

PUT/v2/accounts/{account_id}/permissions/roles/{role_id}
curl -X PUT 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles/{role_id}' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Upload manager",
  "description": "Responsible for managing uploads and uploading new assets.",
  "system_policy_ids": [
    "cld::policy::global::upload_presets::manage",
    "cld::policy::global::folder_and_asset_management::create_asset"
  ]
}'
Response
{
  "data": {
    "policies": [
      {
        "id": "cld::policy::global::upload_presets::manage",
        "name": "Manage upload settings",
        "description": "View, create, modify, or delete upload settings, such as upload presets, upload mappings, and upload defaults.",
        "scope_type": "prodenv",
        "permission_type": "global",
        "policy_statement": "permit(principal, action, resource is Cloudinary::UploadPreset);\npermit(principal, action, resource is Cloudinary::UploadMapping);\npermit(principal, action == Cloudinary::Action::\"update_settings\", resource is Cloudinary::ProductEnvironment);\npermit(principal, action, resource == Cloudinary::Feature::\"cld::global::upload_settings::manage\");\npermit(principal, action, resource == Cloudinary::Feature::\"cld::global::upload_settings::access\");\n",
        "category": "Settings",
        "sub_category": "Upload Settings",
        "created_at": 1719475215,
        "updated_at": 1719475215
      },
      {
        "id": "cld::policy::global::folder_and_asset_management::create_asset",
        "name": "Upload assets",
        "description": "Upload assets to any folder, including the root, without requiring specific folder permissions. Includes the option to select an upload preset and apply tags and metadata.",
        "scope_type": "prodenv",
        "permission_type": "global",
        "policy_statement": "permit(principal, action in [Cloudinary::Action::\"create\"], resource is Cloudinary::Asset);",
        "category": "Management",
        "sub_category": "Folder and asset management",
        "created_at": 1719475215,
        "updated_at": 1719475215
      }
    ],
    "id": "upload_manager_12334565",
    "name": "Upload manager",
    "description": "Responsible for managing uploads and uploading new assets.",
    "management_type": "custom",
    "permission_type": "global",
    "scope_type": "prodenv",
    "created_at": 1719475216,
    "updated_at": 1719475216
  }
}

Delete custom role

Delete a specific custom role.

Path parameters

  • account_id stringRequired

    Account ID

  • role_id stringRequired

    A unique identifier for the role.

Query parameters

  • force boolean

    Determines whether the role should be deleted when it has associated principals.

    • true: Deletes the role even if it has associated principals.
    • false (default): Prevents deletion if the role has associated principals. You must manually unassociate the principals before deleting the role.

Responses

204 Successful operation

No response body.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

DEL/v2/accounts/{account_id}/permissions/roles/{role_id}
curl -X DELETE 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles/{role_id}' \
  -u 'API_KEY:API_SECRET'
Response
{
  "error": {
    "category": "user_error",
    "code": "ACCOUNTS_00006",
    "message": "invalid credentials"
  }
}

Get a role's principals

Retrieve all principals associated with a specific role.

Path parameters

  • account_id stringRequired

    Account ID

  • role_id stringRequired

    A unique identifier for the role.

Query parameters

  • scope_type string

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string

    The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

    • <product_environment_id>
  • verbose boolean

    Determines whether the response contains all the parameters described below (true), or only id and principal_type (false). Default: false

  • folder_id string
    • In the Get role endpoint, the specified folder_id is included in the policy_statement parameter of the response. If no folder_id is specified, the policy_statement shows a placeholder for the folder_id where relevant.
    • In the Get a principal's roles, Get a role's principals, and Inspect endpoints, the results are filtered by the specified folder_id. Only roles or principals with policy_statement parameters associated with that folder_id are returned.
  • asset_id string

    Not currently supported.

  • collection_id string
    • In the Get role endpoint, the specified collection_id is included in the policy_statement parameter of the response. If no collection_id is specified, the policy_statement shows a placeholder for the collection_id where relevant.
    • In the Get a principal's roles and Get a role's principals endpoints, the results are filtered by the specified collection_id. Only roles or principals with policy_statement parameters associated with that collection_id are returned.
  • param_key string[]

    The type of content instance the role applies to, either folder_id or collection_id. Use together with param_value to retrieve role assignments as they apply to a specific instance.

    example ["folder_id"]
  • param_value string[]

    The ID of the content instance (for example, a specific folder or collection). Use together with param_key to retrieve roles as they apply to a specific instance.

    example ["asdfjkl12347890"]

Responses

200 Successful operation
application/json
PrincipalsResponse
  • data PrincipalResponseData[]

    An array of principals.

    ShowHide child attributes of data
    Items PrincipalResponseData
    • id stringRequired

      The unique identifier of the principal.

      example "1234abc"
    • type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • role_id string
    • policy_parameters object
    • scope_type string

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable
    • created_at integer
      format int64 Signed 64-bit integer
    • updated_at integer
      format int64 Signed 64-bit integer
401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/roles/{role_id}/principals
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles/{role_id}/principals' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": [
    {
      "id": "1234abc",
      "type": "user",
      "role_id": "marketing_content_contributor_1357fhe",
      "policy_parameters": {
        "folder_id": "asdfjkl12347890"
      },
      "scope_type": "prodenv",
      "scope_id": "975l29lz02jt0836fhwi",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "akwut728390anvy52sxgti",
      "type": "apiKey",
      "role_id": "marketing_content_contributor_1357fhe",
      "policy_parameters": {
        "folder_id": "asdfjkl12347890"
      },
      "scope_type": "prodenv",
      "scope_id": "975l29lz02jt0836fhwi",
      "created_at": 1719475216,
      "updated_at": 1719475216
    }
  ]
}

Assign principals to a role

Add or remove principals associated with a role.

Path parameters

  • account_id stringRequired

    Account ID

  • role_id stringRequired

    A unique identifier for the role.

Body Required application/json

Principals details.

UpdateRolePrincipalsRequest
  • operation string

    Specifies the operation to perform. Use add to associate or remove to disassociate.

    example "add"
    enum "add" "remove"
  • principals UpdateRolePrincipal[]
    ShowHide child attributes of principals
    Items UpdateRolePrincipal
    • principal_type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • principal_id stringRequired

      The unique identifier of the principal.

      example "1234abc"
    • scope_id stringnullable

      The ID of a specific product environment where the role is applied. This parameter is only relevant if scope_type is "prodenv".

      example "975l29lz02jt0836fhwi"
    • policy_parameters object

      For roles with permission_type set to content, provide the ID of the specific folder or collection you want the role to apply to, for example, {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement, written in Cedar language.

Responses

200 Successful operation

No response body.

400 Missing fields, invalid fields
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

PUT/v2/accounts/{account_id}/permissions/roles/{role_id}/principals
curl -X PUT 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles/{role_id}/principals' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "operation": "add",
  "principals": [
    {
      "principal_type": "user",
      "principal_id": "1234abc",
      "scope_id": "975l29lz02jt0836fhwi",
      "policy_parameters": {
        "folder_id": "asdfjkl12347890"
      }
    }
  ]
}'
Response
{
  "error": {
    "category": "user_error",
    "code": "ACCOUNTS_00005",
    "message": "missing fields",
    "details": {
      "fields": [
        "role_id"
      ]
    }
  }
}

Custom Policies

View and manage the custom policies that control permissions in your account and product environments. Each policy includes a statement defined in Cedar.

For more information on writing Cedar statements for custom policies, see the Cedar official documentation.

Get custom policies

Retrieve all custom permission policies defined for a specific scope. The scope can be at the account level or within a specific product environment.

Notes:

  • If scope_type isn't specified as prodenv, the account-level policies will be returned.

  • If scope_type is specified as prodenv, scope_id is required.

Path parameters

  • account_id stringRequired

    Account ID

Query parameters

  • scope_type string

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string

    The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

    • <product_environment_id>
  • enabled booleannullable

    Filter policies by enabled status (true/false).

  • cursor string

    A pagination cursor for fetching subsequent results.

Responses

200 Successful operation
application/json
CustomPoliciesResponse
  • data CustomPolicyResponseData[]

    An array of custom policies.

    ShowHide child attributes of data
    Items CustomPolicyResponseData
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

      example "975l29lz02jt0836fhwi"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • enabled booleanRequired

      Whether the policy is enabled or not

      example true
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
  • next_cursor string

    When a request has more results to return, the next_cursor value is returned as part of the response. You can then specify this value as the cursor parameter of a following request.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/policies/custom
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/custom' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": [
    {
      "id": "12jf789l12hwiuencl7aaqey",
      "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
      "description": "Permit read access to the Clothing folder with external ID asdfjkl12347890.",
      "scope_type": "prodenv",
      "scope_id": "975l29lz02jt0836fhwi",
      "name": "Read access to Clothing folder",
      "enabled": true,
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "13890asdhjfqyewiurzbxn273",
      "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"update\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
      "description": "Permit updating the Clothing folder with external ID asdfjkl12347890.",
      "scope_type": "prodenv",
      "scope_id": "975l29lz02jt0836fhwi",
      "name": "Update access to Clothing folder",
      "enabled": true,
      "created_at": 1719475216,
      "updated_at": 1719475216
    }
  ]
}

Create custom policy

Create a new custom policy with a statement defined in Cedar. This policy specifies permissions for a principal, allowing a specific action on a designated resource, within a particular scope.

Learn more about creating a new custom policy

Path parameters

  • account_id stringRequired

    Account ID

Body Required application/json

Policy details.

CustomPolicy
  • policy_statement stringRequired

    A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

    example "permit(principal == Cloudinary::APIKey::\\\"1234\\\",action==Cloudinary::Action::\\\"read\\\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\\\"asdfjkl12347890\\\")} ;\n"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    The ID of a specific product environment, or "all" product environments, where the policy is applied. Required and only relevant if scope_type is "prodenv".

    • <product_environment_id>
    • all Note: The "all" specification is relevant only when creating or updating a policy.
    example "975l29lz02jt0836fhwi"
  • name stringRequired

    The name assigned to the policy.

    example "Read access to Clothing folder"
  • enabled booleannullable

    Indicates whether the policy is currently active. Can be "true" (enabled) or "false" (disabled).

    default trueexample true

Responses

201 Policy created successfully
application/json
CustomPolicyResponse
  • data CustomPolicyResponseData
    ShowHide child attributes of data
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

      example "975l29lz02jt0836fhwi"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • enabled booleanRequired

      Whether the policy is enabled or not

      example true
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
400 Missing fields, invalid field, or invalid Cedar statement
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

409 Already exists for the scope
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

POST/v2/accounts/{account_id}/permissions/policies/custom
curl -X POST 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/custom' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
  "description": "Permit read access to the Clothing folder with external ID asdfjkl12347890.",
  "scope_type": "prodenv",
  "scope_id": "975l29lz02jt0836fhwi",
  "name": "Read access to Clothing folder",
  "enabled": true
}'
Response
{
  "data": {
    "id": "12jf789l12hwiuencl7aaqey",
    "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
    "description": "Permit read access to the Clothing folder with external ID asdfjkl12347890.",
    "scope_type": "prodenv",
    "scope_id": "975l29lz02jt0836fhwi",
    "name": "Read access to Clothing folder",
    "enabled": true,
    "created_at": 1719475216,
    "updated_at": 1719475216
  }
}

Get custom policy

Get a specific custom policy.

Path parameters

  • account_id stringRequired

    Account ID

  • policy_id stringRequired

    A unique identifier for the custom permission policy.

Responses

200 Successful operation
application/json
CustomPolicyResponse
  • data CustomPolicyResponseData
    ShowHide child attributes of data
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

      example "975l29lz02jt0836fhwi"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • enabled booleanRequired

      Whether the policy is enabled or not

      example true
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/policies/custom/{policy_id}
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/custom/{policy_id}' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": {
    "id": "12jf789l12hwiuencl7aaqey",
    "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
    "description": "Permit read access to the Clothing folder with external ID asdfjkl12347890.",
    "scope_type": "prodenv",
    "scope_id": "975l29lz02jt0836fhwi",
    "name": "Read access to Clothing folder",
    "enabled": true,
    "created_at": 1719475216,
    "updated_at": 1719475216
  }
}

Update custom policy

Update a specific custom policy by providing the entire policy entity in the request body. Ensure the new policy_statement includes modifications. Existing permissions will be replaced with the new data.

Note: Updating a policy with an identical policy_statement will trigger a 409 error.

Path parameters

  • account_id stringRequired

    Account ID

  • policy_id stringRequired

    A unique identifier for the custom permission policy.

Body Required application/json

Policy details

UpdateCustomPolicy
  • policy_statement stringRequired

    A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

    example "permit(principal == Cloudinary::APIKey::\\\"1234\\\",action==Cloudinary::Action::\\\"read\\\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\\\"asdfjkl12347890\\\")} ;\n"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    The ID of a specific product environment, or "all" product environments, where the policy is applied. Required and only relevant if scope_type is "prodenv".

    • <product_environment_id>
    • all Note: The "all" specification is relevant only when creating or updating a policy.
    example "975l29lz02jt0836fhwi"
  • name stringRequired

    The name assigned to the policy.

    example "Read access to Clothing folder"
  • enabled booleanRequirednullable

    Indicates whether the policy is currently active. Can be "true" (enabled) or "false" (disabled).

    default trueexample true

Responses

200 Policy updated successfully
application/json
CustomPolicyResponse
  • data CustomPolicyResponseData
    ShowHide child attributes of data
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

      example "975l29lz02jt0836fhwi"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • enabled booleanRequired

      Whether the policy is enabled or not

      example true
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
400 Missing fields, invalid field, or invalid Cedar statement
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

409 Conflict
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

PUT/v2/accounts/{account_id}/permissions/policies/custom/{policy_id}
curl -X PUT 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/custom/{policy_id}' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
  "description": "Permit read access to the Accessories folder with external ID asdfjkl12347890.",
  "scope_type": "prodenv",
  "scope_id": "975l29lz02jt0836fhwi",
  "name": "Read access to Accessories folder",
  "enabled": true
}'
Response
{
  "data": {
    "id": "12jf789l12hwiuencl7aaqey",
    "policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;",
    "description": "Permit read access to the Accessories folder with external ID asdfjkl12347890.",
    "scope_type": "prodenv",
    "scope_id": "975l29lz02jt0836fhwi",
    "name": "Read access to Accessories folder",
    "enabled": true,
    "created_at": 1719475216,
    "updated_at": 1719475216
  }
}

Delete custom policy

Delete a specific custom policy.

Path parameters

  • account_id stringRequired

    Account ID

  • policy_id stringRequired

    A unique identifier for the custom permission policy.

Responses

204 Successful operation

No response body.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

DEL/v2/accounts/{account_id}/permissions/policies/custom/{policy_id}
curl -X DELETE 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/custom/{policy_id}' \
  -u 'API_KEY:API_SECRET'
Response
{
  "error": {
    "category": "user_error",
    "code": "ACCOUNTS_00006",
    "message": "invalid credentials"
  }
}

Effective Policies

View all the system and custom policies that are granted to a principal.

Get effective policies

Retrieve all roles (along with their system permission policies) associated with principals, and all custom permission policies directly added to principals, all within a specified scope.

Optionally specify a principal to only include roles and policies associated with that principal.

Path parameters

  • account_id stringRequired

    Account ID

Query parameters

  • scope_type string

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string

    The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

    • <product_environment_id>
  • principal_type string

    The type of principal you want to retrieve roles or permission policies for.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • principal_id string

    The unique identifier of the principal you want to retrieve roles or permission policies for.

    Notes:

    • This parameter is mandatory if principal_type is provided.
    • Ensure the specified ID belongs to a principle of the specified type.

Responses

200 Successful operation
application/json
EffectivePoliciesResponse
  • data object
    ShowHide child attributes of data
    • principals PrincipalRole[]
      ShowHide child attributes of principals
      Items PrincipalRole
      • principal_type string

        The type of principal you want to retrieve roles or permission policies for.

        • user

        • group

        • apiKey

        • provisioningKey

        example "user"
      • principal_id string

        The unique identifier of the principal.

        example "1234abc"
      • roles EffectiveRole[]

        A list of all the roles that are added to this principal.

        ShowHide child attributes of roles
        Items EffectiveRole
        • id string

          The unique identifier of the role.

          example "custom::global::admin"
        • system_policies EffectivePolicy[]

          A list of all the predefined permission policies that are associated with this role.

          ShowHide child attributes of system_policies
          Items EffectivePolicy
          • id string

            The unique identifier of the permission policy.

            example "cld::global::api_keys::manage"
          • policy_statement string

            A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

            example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"
    • custom_policies EffectivePolicy[]
      ShowHide child attributes of custom_policies
      Items EffectivePolicy
      • id string

        The unique identifier of the permission policy.

        example "cld::global::api_keys::manage"
      • policy_statement string

        A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

        example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"
400 Invalid field
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/policies/effective
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/effective' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": {
    "principals": [
      {
        "principal_type": "user",
        "principal_id": "1234abc",
        "roles": [
          {
            "id": "upload_manager_12334565",
            "system_policies": [
              {
                "id": "cld::policy::global::upload_presets::manage",
                "policy_statement": "permit (principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::\"read\", resource is Cloudinary::UploadPreset);"
              },
              {
                "id": "cld::policy::global::folder_and_asset_management::create_asset",
                "policy_statement": "permit(principal == Cloudinary::user::\\\"1234abc\\\", action, resource is Cloudinary::UploadPreset);\npermit(principal == Cloudinary::user::\\\"1234abc\\\", action, resource is Cloudinary::UploadMapping);\npermit(principal == Cloudinary::user::\\\"1234abc\\\", action == Cloudinary::Action::\"update_settings\", resource is Cloudinary::ProductEnvironment);\npermit(principal == Cloudinary::user::\\\"1234abc\\\", action, resource == Cloudinary::Feature::\"cld::global::upload_settings::manage\");\npermit(principal == Cloudinary::user::\\\"1234abc\\\", action, resource == Cloudinary::Feature::\"cld::global::upload_settings::access\");\n"
              }
            ]
          },
          {
            "id": "cld::role::prodenv::reports",
            "system_policies": [
              {
                "id": "cld::policy::global::reports::delivery::view",
                "policy_statement": "permit(principal == Cloudinary::user::\\\"1234abc\\\", action, resource == Cloudinary::Feature::\"cld::global::reports::delivery::view\");\npermit(principal == Cloudinary::user::\\\"1234abc\\\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Report) when {resource.type == \"delivery\"};\n"
              },
              {
                "id": "cld::policy::global::reports::errors::view",
                "policy_statement": "permit (pprincipal == Cloudinary::user::\"1234abc\", action, resource == Cloudinary::Feature::\"cld::global::reports::errors::view\");"
              },
              {
                "id": "cld::policy::global::reports::usage::view",
                "policy_statement": "permit (principal == Cloudinary::user::\\\"1234abc\\\", action, resource == Cloudinary::Feature::\"cld::global::reports::usage::view\");\npermit (principal == Cloudinary::user::\\\"1234abc\\\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Report) when { resource.type == \"env_usage\" };\n"
              }
            ]
          }
        ]
      }
    ],
    "custom_policies": [
      {
        "id": "12jf789l12hwiuencl7aaqey",
        "policy_statement": "permit(principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")};"
      },
      {
        "id": "12jf789l12hwiuencl7aaqey",
        "policy_statement": "permit(principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::\"update\", resource is Cloudinary::Folder) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")};"
      }
    ]
  }
}

Get a principal's roles

Retrieve all roles associated with a specific principal.

Path parameters

  • account_id stringRequired

    Account ID

Query parameters

  • principal_type stringRequired

    The type of principal you want to retrieve roles or permission policies for.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • principal_id stringRequired

    The unique identifier of the principal you want to retrieve roles or permission policies for.

    Notes:

    • This parameter is mandatory if principal_type is provided.
    • Ensure the specified ID belongs to a principle of the specified type.
  • permission_type stringRequired

    Specifies whether to retrieve roles whose permissions apply globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

    example "global"
    enum "global" "content"
  • management_type string

    Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

    example "system"
    enum "system" "custom"
  • scope_type string

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string

    The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

    • <product_environment_id>
  • folder_id string
    • In the Get role endpoint, the specified folder_id is included in the policy_statement parameter of the response. If no folder_id is specified, the policy_statement shows a placeholder for the folder_id where relevant.
    • In the Get a principal's roles, Get a role's principals, and Inspect endpoints, the results are filtered by the specified folder_id. Only roles or principals with policy_statement parameters associated with that folder_id are returned.
  • asset_id string

    Not currently supported.

  • collection_id string
    • In the Get role endpoint, the specified collection_id is included in the policy_statement parameter of the response. If no collection_id is specified, the policy_statement shows a placeholder for the collection_id where relevant.
    • In the Get a principal's roles and Get a role's principals endpoints, the results are filtered by the specified collection_id. Only roles or principals with policy_statement parameters associated with that collection_id are returned.
  • param_key string[]

    The type of content instance the role applies to, either folder_id or collection_id. Use together with param_value to retrieve role assignments as they apply to a specific instance.

    example ["folder_id"]
  • param_value string[]

    The ID of the content instance (for example, a specific folder or collection). Use together with param_key to retrieve roles as they apply to a specific instance.

    example ["asdfjkl12347890"]

Responses

200 Successful operation
application/json
PrincipalRolesResponse
  • data PrincipalRolesData[]
    ShowHide child attributes of data
    Items PrincipalRolesData
    • id stringRequired

      The unique identifier of the role.

    • name stringRequired

      The name of the role.

    • description stringnullable

      A short description of the role.

    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether permissions apply globally or to specific content.

      example "global"
      enum "global" "content"
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

    • policy_parameters objectnullable

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integer
    • updated_at integerRequired

      Last updated time of the policy in epoch time.

      format int64 Signed 64-bit integer
400 Missing fields, invalid fields
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/principal_roles
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/principal_roles?principal_type=user&principal_id=&permission_type=global' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": [
    {
      "id": "cld::role::account::reports",
      "name": "Reports",
      "description": "View account-level reports and usage metrics, including audit logs, dashboard usage summaries, and account-wide activity reports.",
      "management_type": "system",
      "permission_type": "global",
      "scope_type": "account",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "upload_manager_12334565",
      "name": "Upload manager",
      "description": "Responsible for managing upload presets and uploading new assets.",
      "management_type": "custom",
      "permission_type": "global",
      "scope_type": "prodenv",
      "scope_id": "975l29lz02jt0836fhwi",
      "created_at": 1719475216,
      "updated_at": 1719475216
    },
    {
      "id": "marketing_content_contributor_1357fhe",
      "name": "Marketing content contributor",
      "description": "View all assets in selected folders and contribute to those folders, without permission to download.",
      "management_type": "custom",
      "permission_type": "content",
      "policy_parameters": {
        "folder_id": "asdfjkl12347890"
      },
      "scope_type": "prodenv",
      "scope_id": "975l29lz02jt0836fhwi",
      "created_at": 1719475215,
      "updated_at": 1719475215
    }
  ]
}

Assign roles to a principal

Add or remove roles associated with a principal.

Path parameters

  • account_id stringRequired

    Account ID

Body Required application/json

Principal and roles details.

UpdatePrincipalRolesRequest
  • operation string

    Specifies the operation to perform. Use add to associate or remove to disassociate.

    example "add"
    enum "add" "remove"
  • principal Principal
    ShowHide child attributes of principal
    • type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • id stringRequired

      The unique identifier of the principal.

      example "1234abc"
  • roles RoleToManage[]
    ShowHide child attributes of roles
    Items RoleToManage
    • id stringRequired

      The unique identifier of the role you want to assign.

      example "marketing_content_contributor_1357fhe"
    • scope_id string

      The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

      example "975l29lz02jt0836fhwi"
    • policy_parameters object

      Defines the content instance that the role applies to. Specify the content type (folder_id or collection_id) and its corresponding ID. For example, {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).

Responses

200 Successful operation

No response body.

400 Missing fields, invalid fields
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

403 Not allowed
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

PUT/v2/accounts/{account_id}/permissions/principal_roles
curl -X PUT 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/principal_roles' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "operation": "add",
  "principal": {
    "type": "user",
    "id": "1234abc"
  },
  "roles": [
    {
      "id": "marketing_content_contributor_1357fhe",
      "scope_id": "975l29lz02jt0836fhwi",
      "policy_parameters": {
        "folder_id": "asdfjkl12347890"
      }
    }
  ]
}'
Response
{
  "error": {
    "category": "user_error",
    "code": "ACCOUNTS_00005",
    "message": "missing fields",
    "details": {
      "fields": [
        "principal_type"
      ]
    }
  }
}

Inspect

Retrieves principals and their assigned roles within a specified scope, based on query filters.

Use this endpoint to determine which users, groups, API keys, or account API keys have roles applied at:

  • A specific scope_type ("account" or "prodenv")
  • A specific scope_id (for product environments)
  • Optional content filters (such as folder_id, collection_id, or param_key / param_value)
  • Optional principal_type (and principal_id)

The response includes all principals that match the specified filters, along with the roles applied to them within that context.

This endpoint is useful when you want to:

  • Audit who has access within a given scope
  • Identify all principals assigned to roles for a specific folder, collection, asset, or product environment
  • Retrieve role assignments dynamically based on filtering criteria

Path parameters

  • account_id stringRequired

    Account ID

Query parameters

  • scope_type stringRequired

    Specifies the level for retrieving policies or roles, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string

    The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

    • <product_environment_id>
  • principal_type string

    The type of principal you want to retrieve roles or permission policies for.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • principal_id string

    The unique identifier of the principal you want to retrieve roles or permission policies for.

    Notes:

    • This parameter is mandatory if principal_type is provided.
    • Ensure the specified ID belongs to a principle of the specified type.
  • folder_id string
    • In the Get role endpoint, the specified folder_id is included in the policy_statement parameter of the response. If no folder_id is specified, the policy_statement shows a placeholder for the folder_id where relevant.
    • In the Get a principal's roles, Get a role's principals, and Inspect endpoints, the results are filtered by the specified folder_id. Only roles or principals with policy_statement parameters associated with that folder_id are returned.
  • asset_id string

    Not currently supported.

  • collection_id string
    • In the Get role endpoint, the specified collection_id is included in the policy_statement parameter of the response. If no collection_id is specified, the policy_statement shows a placeholder for the collection_id where relevant.
    • In the Get a principal's roles and Get a role's principals endpoints, the results are filtered by the specified collection_id. Only roles or principals with policy_statement parameters associated with that collection_id are returned.
  • param_key string[]

    The type of content instance the role applies to, either folder_id or collection_id. Use together with param_value to retrieve role assignments as they apply to a specific instance.

    example ["folder_id"]
  • param_value string[]

    The ID of the content instance (for example, a specific folder or collection). Use together with param_key to retrieve roles as they apply to a specific instance.

    example ["asdfjkl12347890"]
  • cursor string

    A pagination cursor for fetching subsequent results.

Responses

200 Successful operation
application/json
PrincipalRolesInspectResponse
  • data object
    ShowHide child attributes of data
    • principals PrincipalRolesInspectData[]
      ShowHide child attributes of principals
      Items PrincipalRolesInspectData
      • type stringRequired

        The type of principal.

        example "user"
        enum "user" "group" "apiKey" "provisioningKey"
      • id stringRequired

        The unique identifier of the principal.

      • roles PrincipalRolesData[]Required
        ShowHide child attributes of roles
        Items PrincipalRolesData
        • id stringRequired

          The unique identifier of the role.

        • name stringRequired

          The name of the role.

        • description stringnullable

          A short description of the role.

        • management_type stringRequired

          Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

          example "system"
          enum "system" "custom"
        • permission_type stringRequired

          Specifies whether permissions apply globally or to specific content.

          example "global"
          enum "global" "content"
        • scope_type stringRequired

          Specifies where the role/policy is applied, either at the account level or within product environments.

          example "prodenv"
          enum "account" "prodenv"
        • scope_id stringnullable

          Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

        • policy_parameters objectnullable

          For roles with permission_type set to content, this defines the type of content the role's policies apply to:

          • The content type can be: folder_id or collection_id.
          • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        • created_at integerRequired

          Creation time of the policy in epoch time.

          format int64 Signed 64-bit integer
        • updated_at integerRequired

          Last updated time of the policy in epoch time.

          format int64 Signed 64-bit integer
  • next_cursor string
400 Missing fields, invalid fields
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

GET/v2/accounts/{account_id}/permissions/principal_roles/inspect
curl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/principal_roles/inspect?scope_type=prodenv' \
  -u 'API_KEY:API_SECRET'
Response
{
  "data": {
    "principals": [
      {
        "type": "user",
        "id": "1234abc",
        "roles": [
          {
            "id": "marketing_content_contributor_1357fhe",
            "name": "Marketing content contributor",
            "description": "View all assets in selected folders and contribute to those folders, without permission to download.",
            "management_type": "custom",
            "permission_type": "content",
            "scope_type": "prodenv",
            "scope_id": "975l29lz02jt0836fhwi",
            "policy_parameters": {
              "folder_id": "asdfjkl12347890"
            },
            "created_at": 1719475215,
            "updated_at": 1719475215
          }
        ]
      },
      {
        "type": "user",
        "id": "4567xyz",
        "roles": [
          {
            "id": "campaign_organizer_351766dt",
            "name": "Campaign organizer",
            "description": "Share and download permissions on folders.",
            "management_type": "custom",
            "permission_type": "content",
            "scope_type": "prodenv",
            "scope_id": "975l29lz02jt0836fhwi",
            "policy_parameters": {
              "folder_id": "asdfjkl12347890"
            },
            "created_at": 1719475215,
            "updated_at": 1719475215
          }
        ]
      }
    ]
  }
}

Inspect multiple

Retrieves role assignments for a specified list of principals within a shared scope and optional policy parameters.

Use this endpoint when you already know which principals you want to evaluate and want to check their role assignments in a single request.

In this request:

  • You explicitly provide the principals array in the request body.
  • All principals are evaluated against the same scope_type, optional scope_id, and optional policy_parameters.
  • Unlike Inspect, this endpoint doesn't search for matching principals. It evaluates only the principals you provide.

This endpoint is useful for:

  • Verify role assignments for multiple specified principals at once
  • Comparing role assignments across specific users, groups, or keys
  • Reducing multiple per-principal Inspect calls into a single request

Path parameters

  • account_id stringRequired

    Account ID

Body Required application/json

Role assignments for multiple principals.

InspectRequest
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string
  • principals Principal[]Required
    ShowHide child attributes of principals
    Items Principal
    • type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • id stringRequired

      The unique identifier of the principal.

      example "1234abc"
  • policy_parameters object
  • cursor string

Responses

200 Successful operation
application/json
PrincipalRolesInspectResponse
  • data object
    ShowHide child attributes of data
    • principals PrincipalRolesInspectData[]
      ShowHide child attributes of principals
      Items PrincipalRolesInspectData
      • type stringRequired

        The type of principal.

        example "user"
        enum "user" "group" "apiKey" "provisioningKey"
      • id stringRequired

        The unique identifier of the principal.

      • roles PrincipalRolesData[]Required
        ShowHide child attributes of roles
        Items PrincipalRolesData
        • id stringRequired

          The unique identifier of the role.

        • name stringRequired

          The name of the role.

        • description stringnullable

          A short description of the role.

        • management_type stringRequired

          Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

          example "system"
          enum "system" "custom"
        • permission_type stringRequired

          Specifies whether permissions apply globally or to specific content.

          example "global"
          enum "global" "content"
        • scope_type stringRequired

          Specifies where the role/policy is applied, either at the account level or within product environments.

          example "prodenv"
          enum "account" "prodenv"
        • scope_id stringnullable

          Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

        • policy_parameters objectnullable

          For roles with permission_type set to content, this defines the type of content the role's policies apply to:

          • The content type can be: folder_id or collection_id.
          • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        • created_at integerRequired

          Creation time of the policy in epoch time.

          format int64 Signed 64-bit integer
        • updated_at integerRequired

          Last updated time of the policy in epoch time.

          format int64 Signed 64-bit integer
  • next_cursor string
400 Missing fields, invalid fields
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

401 Authorization required
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

404 Not found
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

500 Internal server error
application/json
ErrorResponse
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

POST/v2/accounts/{account_id}/permissions/principal_roles/inspect
curl -X POST 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/principal_roles/inspect' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "scope_type": "prodenv",
  "scope_id": "975l29lz02jt0836fhwi",
  "principals": [
    {
      "type": "user",
      "id": "1234abc"
    },
    {
      "type": "user",
      "id": "4567xyz"
    },
    {
      "type": "apiKey",
      "id": "a382ltieo893jhioqpg8urp"
    }
  ],
  "policy_parameters": {
    "folder_id": "asdfjkl12347890"
  }
}'
Response
{
  "data": {
    "principals": [
      {
        "type": "user",
        "id": "1234abc",
        "roles": [
          {
            "id": "marketing_content_contributor_1357fhe",
            "name": "Marketing content contributor",
            "description": "View all assets in selected folders and contribute to those folders, without permission to download.",
            "management_type": "custom",
            "permission_type": "content",
            "scope_type": "prodenv",
            "scope_id": "975l29lz02jt0836fhwi",
            "policy_parameters": {
              "folder_id": "asdfjkl12347890"
            },
            "created_at": 1719475215,
            "updated_at": 1719475215
          }
        ]
      },
      {
        "type": "user",
        "id": "4567xyz",
        "roles": [
          {
            "id": "campaign_organizer_351766dt",
            "name": "Campaign organizer",
            "description": "Share and download permissions on folders.",
            "management_type": "custom",
            "permission_type": "content",
            "scope_type": "prodenv",
            "scope_id": "975l29lz02jt0836fhwi",
            "policy_parameters": {
              "folder_id": "<folder_id>"
            },
            "created_at": 1719475215,
            "updated_at": 1719475215
          },
          {
            "id": "cld::role::prodenv::reports",
            "name": "Reports",
            "description": "View product environment reports and usage metrics.",
            "management_type": "system",
            "permission_type": "global",
            "scope_type": "prodenv",
            "scope_id": "975l29lz02jt0836fhwi",
            "created_at": 1719475216,
            "updated_at": 1719475216
          }
        ]
      },
      {
        "type": "apiKey",
        "id": "a382ltieo893jhioqpg8urp",
        "roles": [
          {
            "id": "upload_manager_351766dt",
            "name": "Upload manager",
            "description": "Responsible for managing upload presets and uploading new assets.",
            "management_type": "custom",
            "permission_type": "global",
            "scope_type": "prodenv",
            "scope_id": "975l29lz02jt0836fhwi",
            "created_at": 1719475215,
            "updated_at": 1719475215
          }
        ]
      }
    ]
  }
}

Public

View shared Permissions system utilities, including the system roles and policies catalog, Cedar policy validation, and the Cedar schema. These endpoints are publicly accessible and don't require authentication.

Get system roles and policies catalog

Retrieves the catalog of predefined system roles and their associated policies.

Responses

200 Successful operation
application/json
SystemRolesAndPoliciesCatalogResponse
  • catalog objectRequired
400 Bad request

No response body.

GET/v2/accounts/permissions/public/catalog
curl 'https://api.cloudinary.com/v2/accounts/permissions/public/catalog' \
  -u 'API_KEY:API_SECRET'
Response
{
  "catalog": {
    "system_policies": [
      {
        "id": "cld::policy::global::ml::access",
        "name": "Access the Media Library",
        "description": "Access the Media Library within the Console. Without this permission, users can't view any assets.",
        "category": "Management",
        "sub_category": "General operations",
        "permission_type": "global",
        "scope_type": "prodenv",
        "policy": "permit(principal, action, resource == Cloudinary::Feature::\"cld::global::ml::access\");"
      },
      {
        "id": "cld::policy::content::folder::view_download",
        "name": "View assets",
        "description": "View all assets in the folder and its nested subfolders.",
        "category": "Folder",
        "sub_category": "View and download",
        "permission_type": "content",
        "scope_type": "prodenv",
        "policy": "permit(principal, action == Cloudinary::Action::\"read\", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains(\"<folder_id>\") };"
      }
    ],
    "system_roles": [
      {
        "id": "cld::role::prodenv::master_admin",
        "name": "Master Admin",
        "description": "Fully manage product environment, including settings, product features, dashboards, and reports.",
        "permission_type": "global",
        "scope_type": "prodenv",
        "system_policy_ids": [
          "cld::policy::global::ml::access",
          "cld::policy::global::folder_and_asset_management::view",
          "cld::policy::global::api_keys::manage"
        ]
      },
      {
        "id": "cld::role::folder::viewer",
        "name": "Viewer",
        "description": "View and download public assets.",
        "permission_type": "content",
        "scope_type": "prodenv",
        "system_policy_ids": [
          "cld::policy::content::folder::view_download",
          "cld::policy::content::folder::download_public_assets"
        ]
      }
    ]
  }
}

Validate a Cedar policy

Validate a Cedar policy

Body Required application/json

Cedar policy.

ValidateCedarPolicyRequest
  • policy stringRequired

    The Cedar policy statement to validate.

    example "permit(principal == Cloudinary::APIKy::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"

Responses

200 Successful operation
application/json
ValidateCedarPolicyResponse
  • valid booleanRequired
    example false
  • errors CedarError[]
    ShowHide child attributes of errors
    Items CedarError
    • cedar_message stringRequired
    • cedar_code stringRequired
400 Bad request

No response body.

POST/v2/accounts/permissions/public/validate
curl -X POST 'https://api.cloudinary.com/v2/accounts/permissions/public/validate' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "policy": "permit(principal == Cloudinary::APIKy::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
}'
Response
{
  "valid": false,
  "errors": [
    {
      "cedar_message": "invalid_principal",
      "cedar_code": "ACCOUNTS_00002"
    }
  ]
}

Get Cedar schema

Get Cedar schema

Responses

200 Successful operation
application/json
CedarSchemaResponse
  • schema objectRequired
400 Bad request

No response body.

GET/v2/accounts/permissions/public/schema
curl 'https://api.cloudinary.com/v2/accounts/permissions/public/schema' \
  -u 'API_KEY:API_SECRET'
Response
{
  "schema": {
    "Cloudinary": {
      "actions": {
        "create": {
          "appliesTo": {
            "principalTypes": [
              "APIKey",
              "User",
              "Group"
            ],
            "resourceTypes": [
              "Folder",
              "Asset",
              "Collection"
            ]
          }
        },
        "read": {
          "appliesTo": {
            "principalTypes": [
              "APIKey",
              "User",
              "Group"
            ],
            "resourceTypes": [
              "Folder",
              "Asset",
              "Feature"
            ]
          }
        },
        "move": {
          "appliesTo": {
            "principalTypes": [
              "APIKey",
              "User",
              "Group"
            ],
            "resourceTypes": [
              "Asset",
              "Folder"
            ],
            "context": {
              "type": "Record",
              "attributes": {
                "direction": {
                  "type": "String",
                  "required": false
                }
              }
            }
          }
        }
      },
      "entityTypes": {
        "User": {
          "shape": {
            "type": "Record",
            "attributes": {
              "root": {
                "type": "Boolean",
                "required": false
              }
            }
          }
        },
        "Asset": {
          "shape": {
            "type": "Record",
            "attributes": {
              "ancestor_ids": {
                "type": "Set",
                "element": {
                  "type": "String"
                },
                "required": true
              },
              "resource_type": {
                "type": "String",
                "required": true
              }
            }
          }
        },
        "Folder": {
          "shape": {
            "type": "Record",
            "attributes": {
              "ancestor_ids": {
                "type": "Set",
                "element": {
                  "type": "String"
                },
                "required": true
              },
              "name": {
                "type": "String",
                "required": true
              }
            }
          }
        }
      }
    },
    "MediaFlows": {
      "actions": {
        "read": {
          "appliesTo": {
            "principalTypes": [
              "Cloudinary::User",
              "Cloudinary::Group"
            ],
            "resourceTypes": [
              "EasyFlow",
              "PowerFlow",
              "LogEntry"
            ]
          }
        }
      },
      "entityTypes": {
        "EasyFlow": {},
        "PowerFlow": {},
        "LogEntry": {}
      }
    }
  }
}

Models

ScopeTypeEnum

Show schema
string

Specifies where the role/policy is applied, either at the account level or within product environments.

example "prodenv"
enum "account" "prodenv"

PrincipalTypeEnum

Show schema
string

The type of principal.

example "user"
enum "user" "group" "apiKey" "provisioningKey"

PermissionTypeEnum

Show schema
string

Specifies whether permissions apply globally or to specific content.

example "global"
enum "global" "content"

ManagementTypeEnum

Show schema
string

Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

example "system"
enum "system" "custom"

OperationEnum

Show schema
string

Specifies the operation to perform. Use add to associate or remove to disassociate.

example "add"
enum "add" "remove"

ValidateCedarPolicyRequest

Show schema
object
  • policy stringRequired

    The Cedar policy statement to validate.

    example "permit(principal == Cloudinary::APIKy::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"

UpdateRolePrincipalsRequest

Show schema
object
  • operation string

    Specifies the operation to perform. Use add to associate or remove to disassociate.

    example "add"
    enum "add" "remove"
  • principals UpdateRolePrincipal[]
    ShowHide child attributes of principals
    Items UpdateRolePrincipal
    • principal_type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • principal_id stringRequired

      The unique identifier of the principal.

      example "1234abc"
    • scope_id stringnullable

      The ID of a specific product environment where the role is applied. This parameter is only relevant if scope_type is "prodenv".

      example "975l29lz02jt0836fhwi"
    • policy_parameters object

      For roles with permission_type set to content, provide the ID of the specific folder or collection you want the role to apply to, for example, {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement, written in Cedar language.

CustomPolicy

Show schema
object
  • policy_statement stringRequired

    A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

    example "permit(principal == Cloudinary::APIKey::\\\"1234\\\",action==Cloudinary::Action::\\\"read\\\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\\\"asdfjkl12347890\\\")} ;\n"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    The ID of a specific product environment, or "all" product environments, where the policy is applied. Required and only relevant if scope_type is "prodenv".

    • <product_environment_id>
    • all Note: The "all" specification is relevant only when creating or updating a policy.
    example "975l29lz02jt0836fhwi"
  • name stringRequired

    The name assigned to the policy.

    example "Read access to Clothing folder"
  • enabled booleannullable

    Indicates whether the policy is currently active. Can be "true" (enabled) or "false" (disabled).

    default trueexample true

SystemRolesAndPoliciesCatalogResponse

Show schema
object
  • catalog objectRequired

CedarSchemaResponse

Show schema
object
  • schema objectRequired

ValidateCedarPolicyResponse

Show schema
object
  • valid booleanRequired
    example false
  • errors CedarError[]
    ShowHide child attributes of errors
    Items CedarError
    • cedar_message stringRequired
    • cedar_code stringRequired

CedarError

Show schema
object
  • cedar_message stringRequired
  • cedar_code stringRequired

CreateCustomPolicy

Show schema
CustomPolicy
  • policy_statement stringRequired

    A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

    example "permit(principal == Cloudinary::APIKey::\\\"1234\\\",action==Cloudinary::Action::\\\"read\\\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\\\"asdfjkl12347890\\\")} ;\n"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    The ID of a specific product environment, or "all" product environments, where the policy is applied. Required and only relevant if scope_type is "prodenv".

    • <product_environment_id>
    • all Note: The "all" specification is relevant only when creating or updating a policy.
    example "975l29lz02jt0836fhwi"
  • name stringRequired

    The name assigned to the policy.

    example "Read access to Clothing folder"
  • enabled booleannullable

    Indicates whether the policy is currently active. Can be "true" (enabled) or "false" (disabled).

    default trueexample true

UpdateCustomPolicy

Show schema
object
  • policy_statement stringRequired

    A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

    example "permit(principal == Cloudinary::APIKey::\\\"1234\\\",action==Cloudinary::Action::\\\"read\\\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\\\"asdfjkl12347890\\\")} ;\n"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    The ID of a specific product environment, or "all" product environments, where the policy is applied. Required and only relevant if scope_type is "prodenv".

    • <product_environment_id>
    • all Note: The "all" specification is relevant only when creating or updating a policy.
    example "975l29lz02jt0836fhwi"
  • name stringRequired

    The name assigned to the policy.

    example "Read access to Clothing folder"
  • enabled booleanRequirednullable

    Indicates whether the policy is currently active. Can be "true" (enabled) or "false" (disabled).

    default trueexample true

CustomPolicyResponse

Show schema
object
  • data CustomPolicyResponseData
    ShowHide child attributes of data
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

      example "975l29lz02jt0836fhwi"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • enabled booleanRequired

      Whether the policy is enabled or not

      example true
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216

CustomPolicyResponseData

Show schema
object
  • id stringRequired

    The unique identifier of the policy.

    example "12jf789l12hwiuencl7aaqey"
  • policy_statement stringRequired

    A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

    example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

    example "975l29lz02jt0836fhwi"
  • name stringRequired

    The name of the policy

    example "Read access to Clothing folder"
  • enabled booleanRequired

    Whether the policy is enabled or not

    example true
  • created_at integerRequired

    Creation time of the policy in epoch time.

    format int64 Signed 64-bit integerexample 1719475216
  • updated_at integerRequired

    Last update time of the policy in epoch time.

    format int64 Signed 64-bit integerexample 1719475216

CustomPoliciesResponse

Show schema
object
  • data CustomPolicyResponseData[]

    An array of custom policies.

    ShowHide child attributes of data
    Items CustomPolicyResponseData
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

      example "975l29lz02jt0836fhwi"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • enabled booleanRequired

      Whether the policy is enabled or not

      example true
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
  • next_cursor string

    When a request has more results to return, the next_cursor value is returned as part of the response. You can then specify this value as the cursor parameter of a following request.

SystemPolicyResponseData

Show schema
object
  • id stringRequired

    The unique identifier of the policy.

    example "12jf789l12hwiuencl7aaqey"
  • name stringRequired

    The name of the policy

    example "Read access to Clothing folder"
  • description stringnullable

    A short description of the policy.

    example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • permission_type string

    Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

    - global
    
    - content
    
    example "global"
  • policy_statement stringRequired

    A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

    example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
  • policy_parameters string[]

    For roles with permission_type set to content, this defines the type of content the role's policies apply to:

    • The content type can be: folder_id or collection_id.
    • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
    example ["folder_id"]
  • category string

    The category of the policy.

    example "Management"
  • sub_category string

    The sub-category of the policy.

    example "General operations"
  • created_at integerRequired

    Creation time of the policy in epoch time.

    format int64 Signed 64-bit integerexample 1719475216
  • updated_at integerRequired

    Last update time of the policy in epoch time.

    format int64 Signed 64-bit integerexample 1719475216

SystemPoliciesResponse

Show schema
object
  • data SystemPolicyResponseData[]

    An array of system policies.

    ShowHide child attributes of data
    Items SystemPolicyResponseData
    • id stringRequired

      The unique identifier of the policy.

      example "12jf789l12hwiuencl7aaqey"
    • name stringRequired

      The name of the policy

      example "Read access to Clothing folder"
    • description stringnullable

      A short description of the policy.

      example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • permission_type string

      Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_statement stringRequired

      A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

      example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • category string

      The category of the policy.

      example "Management"
    • sub_category string

      The sub-category of the policy.

      example "General operations"
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      Last update time of the policy in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
  • next_cursor string

    When a request has more results to return, the next_cursor value is returned as part of the response. You can then specify this value as the cursor parameter of a following request.

EffectivePolicy

Show schema
object
  • id string

    The unique identifier of the permission policy.

    example "cld::global::api_keys::manage"
  • policy_statement string

    A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

    example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"

EffectiveRole

Show schema
object
  • id string

    The unique identifier of the role.

    example "custom::global::admin"
  • system_policies EffectivePolicy[]

    A list of all the predefined permission policies that are associated with this role.

    ShowHide child attributes of system_policies
    Items EffectivePolicy
    • id string

      The unique identifier of the permission policy.

      example "cld::global::api_keys::manage"
    • policy_statement string

      A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

      example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"

Principal

Show schema
object
  • type stringRequired

    The type of principal.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • id stringRequired

    The unique identifier of the principal.

    example "1234abc"

PrincipalRole

Show schema
object
  • principal_type string

    The type of principal you want to retrieve roles or permission policies for.

    • user

    • group

    • apiKey

    • provisioningKey

    example "user"
  • principal_id string

    The unique identifier of the principal.

    example "1234abc"
  • roles EffectiveRole[]

    A list of all the roles that are added to this principal.

    ShowHide child attributes of roles
    Items EffectiveRole
    • id string

      The unique identifier of the role.

      example "custom::global::admin"
    • system_policies EffectivePolicy[]

      A list of all the predefined permission policies that are associated with this role.

      ShowHide child attributes of system_policies
      Items EffectivePolicy
      • id string

        The unique identifier of the permission policy.

        example "cld::global::api_keys::manage"
      • policy_statement string

        A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

        example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"

EffectivePoliciesResponse

Show schema
object
  • data object
    ShowHide child attributes of data
    • principals PrincipalRole[]
      ShowHide child attributes of principals
      Items PrincipalRole
      • principal_type string

        The type of principal you want to retrieve roles or permission policies for.

        • user

        • group

        • apiKey

        • provisioningKey

        example "user"
      • principal_id string

        The unique identifier of the principal.

        example "1234abc"
      • roles EffectiveRole[]

        A list of all the roles that are added to this principal.

        ShowHide child attributes of roles
        Items EffectiveRole
        • id string

          The unique identifier of the role.

          example "custom::global::admin"
        • system_policies EffectivePolicy[]

          A list of all the predefined permission policies that are associated with this role.

          ShowHide child attributes of system_policies
          Items EffectivePolicy
          • id string

            The unique identifier of the permission policy.

            example "cld::global::api_keys::manage"
          • policy_statement string

            A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

            example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"
    • custom_policies EffectivePolicy[]
      ShowHide child attributes of custom_policies
      Items EffectivePolicy
      • id string

        The unique identifier of the permission policy.

        example "cld::global::api_keys::manage"
      • policy_statement string

        A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to the Permissions API guide for more information.

        example "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::api_keys::view\");"

Role

Show schema
object
  • name stringRequired

    The name of the role.

    example "Upload manager"
  • description stringnullable

    A short description of the role.

    example "Responsible for managing upload presets and uploading new assets."
  • system_policy_ids string[]

    A list of system permission policy IDs to be included in the role.

    Tip: Get the list of all available predefined policies using the Get system policies method.

CreateRole

Show schema
object
  • id string

    The unique identifier for the role.

    • When creating a new role: If not provided, the system will auto-generate the ID.
    • When updating a role: Specify the ID of the role you want to update.
    example "upload_manager_12334565"
  • permission_type stringRequired

    Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr"). Note: This attrubute is immutable.

    • global
    • content
    example "global"
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • name stringRequired

    The name of the role.

    example "Upload manager"
  • description stringnullable

    A short description of the role.

    example "Responsible for managing upload presets and uploading new assets."
  • system_policy_ids string[]

    A list of system permission policy IDs to be included in the role.

    Tip: Get the list of all available predefined policies using the Get system policies method.

UpdateRole

Show schema
Role
  • name stringRequired

    The name of the role.

    example "Upload manager"
  • description stringnullable

    A short description of the role.

    example "Responsible for managing upload presets and uploading new assets."
  • system_policy_ids string[]

    A list of system permission policy IDs to be included in the role.

    Tip: Get the list of all available predefined policies using the Get system policies method.

RoleResponseData

Show schema
object
  • id stringRequired

    The unique identifier of the role.

    example "cld::role::prodenv::master_admin"
  • name stringRequired

    The name of the role.

    example "Master admin"
  • description stringnullable

    A short description of the role.

    example "Full access."
  • management_type stringRequired

    Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

    example "system"
    enum "system" "custom"
  • permission_type stringRequired

    Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

    - global
    
    - content
    
    example "global"
  • policy_parameters string[]

    For roles with permission_type set to content, this defines the type of content the role's policies apply to:

    • The content type can be: folder_id or collection_id.
    • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
    example ["folder_id"]
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • created_at integerRequired

    The permission policy creation timestamp in epoch time.

    format int64 Signed 64-bit integerexample 1719475216
  • updated_at integerRequired

    The permission policy last updated timestamp in epoch time.

    format int64 Signed 64-bit integerexample 1719475216

RoleResponse

Show schema
object
  • data object
    ShowHide child attributes of data
    • policies SystemPolicyResponseData[]
      ShowHide child attributes of policies
      Items SystemPolicyResponseData
      • id stringRequired

        The unique identifier of the policy.

        example "12jf789l12hwiuencl7aaqey"
      • name stringRequired

        The name of the policy

        example "Read access to Clothing folder"
      • description stringnullable

        A short description of the policy.

        example "Permit read access to the Clothing folder with external ID asdfjkl12347890."
      • scope_type stringRequired

        Specifies where the role/policy is applied, either at the account level or within product environments.

        example "prodenv"
        enum "account" "prodenv"
      • permission_type string

        Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

        - global
        
        - content
        
        example "global"
      • policy_statement stringRequired

        A Cedar policy that permits or forbids a certain action on a certain element to a principal (user, group, or API key).

        example "permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when { resource.ancestor_ids.contains(\"\\<folder_id\\>\") };"
      • policy_parameters string[]

        For roles with permission_type set to content, this defines the type of content the role's policies apply to:

        • The content type can be: folder_id or collection_id.
        • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        example ["folder_id"]
      • category string

        The category of the policy.

        example "Management"
      • sub_category string

        The sub-category of the policy.

        example "General operations"
      • created_at integerRequired

        Creation time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
      • updated_at integerRequired

        Last update time of the policy in epoch time.

        format int64 Signed 64-bit integerexample 1719475216
    • id stringRequired

      The unique identifier of the role.

      example "cld::role::prodenv::master_admin"
    • name stringRequired

      The name of the role.

      example "Master admin"
    • description stringnullable

      A short description of the role.

      example "Full access."
    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • created_at integerRequired

      The permission policy creation timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      The permission policy last updated timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216

UpdateRolePrincipal

Show schema
object
  • principal_type stringRequired

    The type of principal.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • principal_id stringRequired

    The unique identifier of the principal.

    example "1234abc"
  • scope_id stringnullable

    The ID of a specific product environment where the role is applied. This parameter is only relevant if scope_type is "prodenv".

    example "975l29lz02jt0836fhwi"
  • policy_parameters object

    For roles with permission_type set to content, provide the ID of the specific folder or collection you want the role to apply to, for example, {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement, written in Cedar language.

PrincipalResponseData

Show schema
object
  • id stringRequired

    The unique identifier of the principal.

    example "1234abc"
  • type stringRequired

    The type of principal.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • role_id string
  • policy_parameters object
  • scope_type string

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable
  • created_at integer
    format int64 Signed 64-bit integer
  • updated_at integer
    format int64 Signed 64-bit integer

PrincipalsResponse

Show schema
object
  • data PrincipalResponseData[]

    An array of principals.

    ShowHide child attributes of data
    Items PrincipalResponseData
    • id stringRequired

      The unique identifier of the principal.

      example "1234abc"
    • type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • role_id string
    • policy_parameters object
    • scope_type string

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable
    • created_at integer
      format int64 Signed 64-bit integer
    • updated_at integer
      format int64 Signed 64-bit integer

RolesResponse

Show schema
object
  • data RoleResponseData[]

    An array of roles.

    ShowHide child attributes of data
    Items RoleResponseData
    • id stringRequired

      The unique identifier of the role.

      example "cld::role::prodenv::master_admin"
    • name stringRequired

      The name of the role.

      example "Master admin"
    • description stringnullable

      A short description of the role.

      example "Full access."
    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

      - global
      
      - content
      
      example "global"
    • policy_parameters string[]

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
      example ["folder_id"]
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • created_at integerRequired

      The permission policy creation timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216
    • updated_at integerRequired

      The permission policy last updated timestamp in epoch time.

      format int64 Signed 64-bit integerexample 1719475216

PrincipalRolesResponse

Show schema
object
  • data PrincipalRolesData[]
    ShowHide child attributes of data
    Items PrincipalRolesData
    • id stringRequired

      The unique identifier of the role.

    • name stringRequired

      The name of the role.

    • description stringnullable

      A short description of the role.

    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether permissions apply globally or to specific content.

      example "global"
      enum "global" "content"
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

    • policy_parameters objectnullable

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integer
    • updated_at integerRequired

      Last updated time of the policy in epoch time.

      format int64 Signed 64-bit integer

PrincipalRolesData

Show schema
object
  • id stringRequired

    The unique identifier of the role.

  • name stringRequired

    The name of the role.

  • description stringnullable

    A short description of the role.

  • management_type stringRequired

    Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

    example "system"
    enum "system" "custom"
  • permission_type stringRequired

    Specifies whether permissions apply globally or to specific content.

    example "global"
    enum "global" "content"
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id stringnullable

    Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

  • policy_parameters objectnullable

    For roles with permission_type set to content, this defines the type of content the role's policies apply to:

    • The content type can be: folder_id or collection_id.
    • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
  • created_at integerRequired

    Creation time of the policy in epoch time.

    format int64 Signed 64-bit integer
  • updated_at integerRequired

    Last updated time of the policy in epoch time.

    format int64 Signed 64-bit integer

PrincipalRolesInspectResponse

Show schema
object
  • data object
    ShowHide child attributes of data
    • principals PrincipalRolesInspectData[]
      ShowHide child attributes of principals
      Items PrincipalRolesInspectData
      • type stringRequired

        The type of principal.

        example "user"
        enum "user" "group" "apiKey" "provisioningKey"
      • id stringRequired

        The unique identifier of the principal.

      • roles PrincipalRolesData[]Required
        ShowHide child attributes of roles
        Items PrincipalRolesData
        • id stringRequired

          The unique identifier of the role.

        • name stringRequired

          The name of the role.

        • description stringnullable

          A short description of the role.

        • management_type stringRequired

          Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

          example "system"
          enum "system" "custom"
        • permission_type stringRequired

          Specifies whether permissions apply globally or to specific content.

          example "global"
          enum "global" "content"
        • scope_type stringRequired

          Specifies where the role/policy is applied, either at the account level or within product environments.

          example "prodenv"
          enum "account" "prodenv"
        • scope_id stringnullable

          Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

        • policy_parameters objectnullable

          For roles with permission_type set to content, this defines the type of content the role's policies apply to:

          • The content type can be: folder_id or collection_id.
          • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
        • created_at integerRequired

          Creation time of the policy in epoch time.

          format int64 Signed 64-bit integer
        • updated_at integerRequired

          Last updated time of the policy in epoch time.

          format int64 Signed 64-bit integer
  • next_cursor string

PrincipalRolesInspectData

Show schema
object
  • type stringRequired

    The type of principal.

    example "user"
    enum "user" "group" "apiKey" "provisioningKey"
  • id stringRequired

    The unique identifier of the principal.

  • roles PrincipalRolesData[]Required
    ShowHide child attributes of roles
    Items PrincipalRolesData
    • id stringRequired

      The unique identifier of the role.

    • name stringRequired

      The name of the role.

    • description stringnullable

      A short description of the role.

    • management_type stringRequired

      Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).

      example "system"
      enum "system" "custom"
    • permission_type stringRequired

      Specifies whether permissions apply globally or to specific content.

      example "global"
      enum "global" "content"
    • scope_type stringRequired

      Specifies where the role/policy is applied, either at the account level or within product environments.

      example "prodenv"
      enum "account" "prodenv"
    • scope_id stringnullable

      Returned only if the scope type is product environment. Can be "all" to represent all product environments or an ID of a specific product environment.

    • policy_parameters objectnullable

      For roles with permission_type set to content, this defines the type of content the role's policies apply to:

      • The content type can be: folder_id or collection_id.
      • When assigning the role, provide the instance, e.g. {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).
    • created_at integerRequired

      Creation time of the policy in epoch time.

      format int64 Signed 64-bit integer
    • updated_at integerRequired

      Last updated time of the policy in epoch time.

      format int64 Signed 64-bit integer

UpdatePrincipalRolesRequest

Show schema
object
  • operation string

    Specifies the operation to perform. Use add to associate or remove to disassociate.

    example "add"
    enum "add" "remove"
  • principal Principal
    ShowHide child attributes of principal
    • type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • id stringRequired

      The unique identifier of the principal.

      example "1234abc"
  • roles RoleToManage[]
    ShowHide child attributes of roles
    Items RoleToManage
    • id stringRequired

      The unique identifier of the role you want to assign.

      example "marketing_content_contributor_1357fhe"
    • scope_id string

      The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

      example "975l29lz02jt0836fhwi"
    • policy_parameters object

      Defines the content instance that the role applies to. Specify the content type (folder_id or collection_id) and its corresponding ID. For example, {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).

InspectRequest

Show schema
object
  • scope_type stringRequired

    Specifies where the role/policy is applied, either at the account level or within product environments.

    example "prodenv"
    enum "account" "prodenv"
  • scope_id string
  • principals Principal[]Required
    ShowHide child attributes of principals
    Items Principal
    • type stringRequired

      The type of principal.

      example "user"
      enum "user" "group" "apiKey" "provisioningKey"
    • id stringRequired

      The unique identifier of the principal.

      example "1234abc"
  • policy_parameters object
  • cursor string

RoleToManage

Show schema
object
  • id stringRequired

    The unique identifier of the role you want to assign.

    example "marketing_content_contributor_1357fhe"
  • scope_id string

    The ID of a specific product environment where the policy is applied. This parameter is only relevant if scope_type is "prodenv".

    example "975l29lz02jt0836fhwi"
  • policy_parameters object

    Defines the content instance that the role applies to. Specify the content type (folder_id or collection_id) and its corresponding ID. For example, {"folder_id":"asdfjkl12347890"}. This specification is passed to the policy_statement (Cedar).

ErrorResponse

Show schema
object
  • error Error
    ShowHide child attributes of error
    • category string

      A classification of the error, indicating the general area or type of problem.

    • code string

      A specific error code that uniquely identifies the error condition.

    • message string

      A human-readable message providing a brief explanation of the error and its cause.

    • details object

      Additional contextual information about the error, which may include relevant data.

Error

Show schema
object
  • category string

    A classification of the error, indicating the general area or type of problem.

  • code string

    A specific error code that uniquely identifies the error condition.

  • message string

    A human-readable message providing a brief explanation of the error and its cause.

  • details object

    Additional contextual information about the error, which may include relevant data.