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.
Cloudinary Account Permissions API
Download OpenAPI DocumentAccounts 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:
View all system policies predefined by Cloudinary, which can be associated with roles.
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
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/policies/systemcurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/system' \
-u 'API_KEY:API_SECRET'{
"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"
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}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.
Endpoints
- GET
/v2/accounts/{account_id}/permissions/roles - POST
/v2/accounts/{account_id}/permissions/roles - GET
/v2/accounts/{account_id}/permissions/roles/{role_id} - PUT
/v2/accounts/{account_id}/permissions/roles/{role_id} - DEL
/v2/accounts/{account_id}/permissions/roles/{role_id} - GET
/v2/accounts/{account_id}/permissions/roles/{role_id}/principals - PUT
/v2/accounts/{account_id}/permissions/roles/{role_id}/principals
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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
Responses
200 Successful operation
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
401 Authorization required
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/rolescurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles?permission_type=global' \
-u 'API_KEY:API_SECRET'{
"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
}
]
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}Create a new custom role.
Path parameters
- account_id stringRequired
Account ID
Body Required application/json
Role details.
- 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
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
400 Missing fields or invalid field
- 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
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/rolescurl -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"
]
}'{
"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
}
}{
"data": {
"policies": [
{
"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>\") }; permit(principal, action == Cloudinary::Action::\"read\", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains(\"<folder_id>\") };\n",
"policy_parameters": [
"folder_id"
],
"category": "Folder",
"sub_category": "View and download",
"created_at": 1719475215,
"updated_at": 1719475215
},
{
"id": "cld::policy::content::folder::add_assets",
"name": "Add assets",
"description": "Add assets to the folder by uploading new files, saving an asset as new, or moving existing assets from other folders. Tags and structured metadata can be applied during upload.",
"scope_type": "prodenv",
"permission_type": "content",
"policy_statement": "permit(principal, action == Cloudinary::Action::\"create\", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains(\"<folder_id>\")};\n",
"policy_parameters": [
"folder_id"
],
"category": "Folder",
"sub_category": "Contribute",
"created_at": 1719475215,
"updated_at": 1719475215
}
],
"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"
],
"scope_type": "prodenv",
"created_at": 1719475216,
"updated_at": 1719475216
}
}{
"data": {
"policies": [
{
"id": "cld::policy::global::users_and_groups::manage",
"name": "Manage users and groups",
"description": "View, add, and remove users and groups in the account, and manage group memberships.",
"scope_type": "account",
"permission_type": "global",
"policy_statement": "permit (principal, action , resource is Cloudinary::User); permit (principal, action, resource is Cloudinary::Group); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::users::view\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::users::create\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::users::update\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::users::delete\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::groups::view\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::groups::create\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::groups::update\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::groups::delete\");\n",
"category": "Settings",
"sub_category": "User Management",
"created_at": 1719475215,
"updated_at": 1719475215
},
{
"id": "cld::policy::global::account_security::manage",
"name": "Manage account security settings",
"description": "Define account-wide security settings related to authentication, access control, and user privacy.",
"scope_type": "account",
"policy_statement": "permit (principal, action, resource == Cloudinary::Feature::\"cld::global::account::view\"); permit (principal, action, resource == Cloudinary::Feature::\"cld::global::account::update\"); permit (principal, action == Cloudinary::Action::\"read\", resource is Cloudinary::Account); permit (principal, action == Cloudinary::Action::\"update\", resource is Cloudinary::Account);\n",
"category": "Settings",
"sub_category": "Account Security",
"created_at": 1719475215,
"updated_at": 1719475215
}
],
"id": "sensitive_account_details_manager_88825hl",
"name": "Sensitive account details manager",
"description": "Responsible for managing users and account security.",
"management_type": "custom",
"permission_type": "global",
"scope_type": "account",
"created_at": 1719475216,
"updated_at": 1719475216
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"name"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"scope_type": "account"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "already exists",
"details": {
"fields": [
{
"name": "Admin"
}
]
}
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}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_idis included in thepolicy_statementparameter of the response. If nofolder_idis specified, thepolicy_statementshows a placeholder for thefolder_idwhere 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 withpolicy_statementparameters associated with thatfolder_idare returned.
- In the Get role endpoint, the specified
- asset_id string
Not currently supported.
- collection_id string
- In the Get role endpoint, the specified
collection_idis included in thepolicy_statementparameter of the response. If nocollection_idis specified, thepolicy_statementshows a placeholder for thecollection_idwhere 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 withpolicy_statementparameters associated with thatcollection_idare returned.
- In the Get role endpoint, the specified
- param_key string[]
The type of content instance the role applies to, either
folder_idorcollection_id. Use together withparam_valueto 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
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
401 Authorization required
- 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
- 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
- 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.
/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'{
"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
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"role_id": "manage_transformations_q1829qwnkli"
}
]
}
}
}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
- 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
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
400 Missing fields, invalid field
- 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
- 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
- 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
- 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
- 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
- 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.
/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"
]
}'{
"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
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"name"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"system_policy_ids": "cld::global::upload_presets::sample"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"role_id": "manage_transformations_q1829qwnkli"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "already exists",
"details": {
"fields": [
{
"name": "Admin"
}
]
}
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}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
- 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
- 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
- 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.
/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'{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"role_id": "manage_transformations_q1829qwnkli"
}
]
}
}
}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_typeis "prodenv".- <product_environment_id>
- verbose boolean
Determines whether the response contains all the parameters described below (
true), or onlyidandprincipal_type(false). Default:false - folder_id string
- In the Get role endpoint, the specified
folder_idis included in thepolicy_statementparameter of the response. If nofolder_idis specified, thepolicy_statementshows a placeholder for thefolder_idwhere 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 withpolicy_statementparameters associated with thatfolder_idare returned.
- In the Get role endpoint, the specified
- asset_id string
Not currently supported.
- collection_id string
- In the Get role endpoint, the specified
collection_idis included in thepolicy_statementparameter of the response. If nocollection_idis specified, thepolicy_statementshows a placeholder for thecollection_idwhere 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 withpolicy_statementparameters associated with thatcollection_idare returned.
- In the Get role endpoint, the specified
- param_key string[]
The type of content instance the role applies to, either
folder_idorcollection_id. Use together withparam_valueto 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
- 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 integerformat
int64Signed 64-bit integer - updated_at integerformat
int64Signed 64-bit integer
401 Authorization required
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/roles/{role_id}/principalscurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/roles/{role_id}/principals' \
-u 'API_KEY:API_SECRET'{
"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
}
]
}{
"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
}
]
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"role_id": "manage_transformations_q1829qwnkli"
}
]
}
}
}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.
- operation string
Specifies the operation to perform. Use
addto associate orremoveto 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_typeis "prodenv".example"975l29lz02jt0836fhwi" - policy_parameters object
For roles with
permission_typeset tocontent, 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 thepolicy_statement, written in Cedar language.
Responses
200 Successful operation
No response body.
400 Missing fields, invalid fields
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/roles/{role_id}/principalscurl -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"
}
}
]
}'{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"role_id"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"operation": "subtract"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"role_id": "manage_transformations_q1829qwnkli"
}
]
}
}
}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.
Endpoints
- GET
/v2/accounts/{account_id}/permissions/policies/custom - POST
/v2/accounts/{account_id}/permissions/policies/custom - GET
/v2/accounts/{account_id}/permissions/policies/custom/{policy_id} - PUT
/v2/accounts/{account_id}/permissions/policies/custom/{policy_id} - DEL
/v2/accounts/{account_id}/permissions/policies/custom/{policy_id}
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_typeisn't specified asprodenv, the account-level policies will be returned. -
If
scope_typeis specified asprodenv,scope_idis 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_typeis "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
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/policies/customcurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/custom' \
-u 'API_KEY:API_SECRET'{
"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
}
]
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}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.
- 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).
defaulttrueexampletrue
Responses
201 Policy created successfully
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
400 Missing fields, invalid field, or invalid Cedar statement
- 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
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/policies/customcurl -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
}'{
"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
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"name"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"scope_type": "account"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00002",
"message": "invalid request",
"details": {
"fields": [
{
"policy_statement": "permit(principal == Cloudinary::APIKy::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
},
{
"cedar_errors": [
{
"cedar_message": "invalid_principal"
}
]
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "already exists for the scope",
"details": {
"fields": [
{
"policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
}
]
}
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}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
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
401 Authorization required
- 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
- 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
- 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.
/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'{
"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
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"policy_id": "al18owlkth68901"
}
]
}
}
}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
- 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).
defaulttrueexampletrue
Responses
200 Policy updated successfully
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
400 Missing fields, invalid field, or invalid Cedar statement
- 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
- 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
- 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
- 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
- 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
- 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.
/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
}'{
"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
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"name"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"scope_type": "account"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00002",
"message": "invalid request",
"details": {
"fields": [
{
"policy_statement": "permit(principal == Cloudinary::APIKy::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
},
{
"cedar_errors": [
{
"cedar_message": "invalid_principal"
}
]
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"policy_id": "al18owlkth68901"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "already exists for the scope",
"details": {
"fields": [
{
"policy_statement": "permit(principal == Cloudinary::APIKey::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
}
]
}
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}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
- 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
- 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
- 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.
/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'{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"policy_id": "al18owlkth68901"
}
]
}
}
}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_typeis "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_typeis provided. - Ensure the specified ID belongs to a principle of the specified type.
- This parameter is mandatory if
Responses
200 Successful operation
- 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
- 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
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/policies/effectivecurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/policies/effective' \
-u 'API_KEY:API_SECRET'{
"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\")};"
}
]
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"scope_type": "account"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"scope_id": "55559999333hhx"
}
]
}
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}View roles associated with a specified principal, and add or remove a role associated with a principal.
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_typeis provided. - Ensure the specified ID belongs to a principle of the specified type.
- This parameter is mandatory if
- 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_typeis "prodenv".- <product_environment_id>
- folder_id string
- In the Get role endpoint, the specified
folder_idis included in thepolicy_statementparameter of the response. If nofolder_idis specified, thepolicy_statementshows a placeholder for thefolder_idwhere 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 withpolicy_statementparameters associated with thatfolder_idare returned.
- In the Get role endpoint, the specified
- asset_id string
Not currently supported.
- collection_id string
- In the Get role endpoint, the specified
collection_idis included in thepolicy_statementparameter of the response. If nocollection_idis specified, thepolicy_statementshows a placeholder for thecollection_idwhere 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 withpolicy_statementparameters associated with thatcollection_idare returned.
- In the Get role endpoint, the specified
- param_key string[]
The type of content instance the role applies to, either
folder_idorcollection_id. Use together withparam_valueto 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
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
400 Missing fields, invalid fields
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/principal_rolescurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/principal_roles?principal_type=user&principal_id=&permission_type=global' \
-u 'API_KEY:API_SECRET'{
"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
}
]
}{
"data": [
{
"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",
"policy_parameters": {
"folder_id": "asdfjkl12347890"
},
"created_at": 1719475215,
"updated_at": 1719475215
}
]
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"principal_type"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"scope_type": "account"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00003",
"message": "not found",
"details": {
"fields": [
{
"principal_id": "xyz098ppb"
}
]
}
}
}{
"error": {
"category": "server_error",
"code": "ACCOUNTS_00001",
"message": "something went wrong"
}
}Add or remove roles associated with a principal.
Path parameters
- account_id stringRequired
Account ID
Body Required application/json
Principal and roles details.
- operation string
Specifies the operation to perform. Use
addto associate orremoveto 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_typeis "prodenv".example"975l29lz02jt0836fhwi" - policy_parameters object
Defines the content instance that the role applies to. Specify the content type (
folder_idorcollection_id) and its corresponding ID. For example,{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
Responses
200 Successful operation
No response body.
400 Missing fields, invalid fields
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/principal_rolescurl -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"
}
}
]
}'{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "missing fields",
"details": {
"fields": [
"principal_type"
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00005",
"message": "invalid request",
"details": {
"fields": [
{
"operation": "subtract"
}
]
}
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "invalid credentials"
}
}{
"error": {
"category": "user_error",
"code": "ACCOUNTS_00006",
"message": "not allowed"
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}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, orparam_key/param_value) - Optional
principal_type(andprincipal_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_typeis "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_typeis provided. - Ensure the specified ID belongs to a principle of the specified type.
- This parameter is mandatory if
- folder_id string
- In the Get role endpoint, the specified
folder_idis included in thepolicy_statementparameter of the response. If nofolder_idis specified, thepolicy_statementshows a placeholder for thefolder_idwhere 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 withpolicy_statementparameters associated with thatfolder_idare returned.
- In the Get role endpoint, the specified
- asset_id string
Not currently supported.
- collection_id string
- In the Get role endpoint, the specified
collection_idis included in thepolicy_statementparameter of the response. If nocollection_idis specified, thepolicy_statementshows a placeholder for thecollection_idwhere 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 withpolicy_statementparameters associated with thatcollection_idare returned.
- In the Get role endpoint, the specified
- param_key string[]
The type of content instance the role applies to, either
folder_idorcollection_id. Use together withparam_valueto 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
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
- next_cursor string
400 Missing fields, invalid fields
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/principal_roles/inspectcurl 'https://api.cloudinary.com/v2/accounts/ACCOUNT_ID/permissions/principal_roles/inspect?scope_type=prodenv' \
-u 'API_KEY:API_SECRET'{
"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
}
]
}
]
}
}{
"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": "View and download access to folders containing marketing campaign images and videos.",
"management_type": "custom",
"permission_type": "content",
"scope_type": "prodenv",
"scope_id": "975l29lz02jt0836fhwi",
"policy_parameters": {
"folder_id": "asdfjkl12347890"
},
"created_at": 1719475215,
"updated_at": 1719475215
},
{
"id": "website_admin_2523512",
"name": "Website administrator",
"description": "Manage assets delivered on the website.",
"management_type": "custom",
"permission_type": "content",
"scope_type": "prodenv",
"scope_id": "975l29lz02jt0836fhwi",
"policy_parameters": {
"folder_id": "bgxf992356125643"
},
"created_at": 1719475215,
"updated_at": 1719475215
}
]
}
]
}
}{
"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
},
{
"id": "manage_portals_238haspw",
"name": "Brand portal manager",
"description": "Manage the curation and sharing of brand portals.",
"management_type": "custom",
"permission_type": "global",
"scope_type": "prodenv",
"scope_id": "975l29lz02jt0836fhwi",
"created_at": 1719475215,
"updated_at": 1719475215
}
]
},
{
"type": "apiKey",
"id": "a382ltieo893jhioqpg8urp",
"roles": [
{
"id": "upload_manager_351766dt",
"name": "Manage upload settings",
"description": "Manage settings related to upload management.",
"management_type": "custom",
"permission_type": "global",
"scope_type": "prodenv",
"scope_id": "975l29lz02jt0836fhwi",
"created_at": 1719475215,
"updated_at": 1719475215
}
]
}
]
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}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
principalsarray in the request body. - All principals are evaluated against the same
scope_type, optionalscope_id, and optionalpolicy_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
Inspectcalls into a single request
Path parameters
- account_id stringRequired
Account ID
Body Required application/json
Role assignments for multiple principals.
- 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
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
- next_cursor string
400 Missing fields, invalid fields
- 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
- 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
- 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
- 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.
/v2/accounts/{account_id}/permissions/principal_roles/inspectcurl -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"
}
}'{
"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
}
]
}
]
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}{
"error": {
"category": "string",
"code": "string",
"message": "string",
"details": {}
}
}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.
Retrieves the catalog of predefined system roles and their associated policies.
Responses
200 Successful operation
- catalog objectRequired
400 Bad request
No response body.
/v2/accounts/permissions/public/catalogcurl 'https://api.cloudinary.com/v2/accounts/permissions/public/catalog' \
-u 'API_KEY:API_SECRET'{
"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
Body Required application/json
Cedar policy.
- 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
- valid booleanRequiredexample
false - errors CedarError[]
ShowHide child attributes of errors
Items CedarError- cedar_message stringRequired
- cedar_code stringRequired
400 Bad request
No response body.
/v2/accounts/permissions/public/validatecurl -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\")} ;"
}'{
"valid": false,
"errors": [
{
"cedar_message": "invalid_principal",
"cedar_code": "ACCOUNTS_00002"
}
]
}Get Cedar schema
Responses
200 Successful operation
- schema objectRequired
400 Bad request
No response body.
/v2/accounts/permissions/public/schemacurl 'https://api.cloudinary.com/v2/accounts/permissions/public/schema' \
-u 'API_KEY:API_SECRET'{
"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
Show schema
Specifies where the role/policy is applied, either at the account level or within product environments.
"prodenv""account" "prodenv"Show schema
The type of principal.
"user""user" "group" "apiKey" "provisioningKey"Show schema
Specifies whether permissions apply globally or to specific content.
"global""global" "content"Show schema
Specifies whether the role's policies are managed by Cloudinary (system) or by the user (custom).
"system""system" "custom"Show schema
Specifies the operation to perform. Use add to associate or remove to disassociate.
"add""add" "remove"Show schema
- 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\")} ;"
Show schema
- operation string
Specifies the operation to perform. Use
addto associate orremoveto 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_typeis "prodenv".example"975l29lz02jt0836fhwi" - policy_parameters object
For roles with
permission_typeset tocontent, 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 thepolicy_statement, written in Cedar language.
Show schema
- 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).
defaulttrueexampletrue
Show schema
- valid booleanRequiredexample
false - errors CedarError[]
ShowHide child attributes of errors
Items CedarError- cedar_message stringRequired
- cedar_code stringRequired
Show schema
- 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).
defaulttrueexampletrue
Show schema
- 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).
defaulttrueexampletrue
Show schema
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
Show schema
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
Show schema
- 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
exampletrue - created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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.
Show schema
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
Show schema
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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.
Show schema
- 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\");"
Show schema
- 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\");"
Show schema
- type stringRequired
The type of principal.
example"user"enum"user""group""apiKey""provisioningKey" - id stringRequired
The unique identifier of the principal.
example"1234abc"
Show schema
- 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\");"
Show schema
- 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\");"
Show schema
- 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.
Show schema
- 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.
Show schema
- 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.
Show schema
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
Show schema
- 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 - contentexample"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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
Last update time of the policy in epoch time.
formatint64Signed 64-bit integerexample1719475216
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
Show schema
- 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_typeis "prodenv".example"975l29lz02jt0836fhwi" - policy_parameters object
For roles with
permission_typeset tocontent, 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 thepolicy_statement, written in Cedar language.
Show schema
- 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 integerformat
int64Signed 64-bit integer - updated_at integerformat
int64Signed 64-bit integer
Show schema
- 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 integerformat
int64Signed 64-bit integer - updated_at integerformat
int64Signed 64-bit integer
Show schema
- 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 - contentexample"global" - policy_parameters string[]
For roles with
permission_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
example["folder_id"] - The content type can be:
- 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.
formatint64Signed 64-bit integerexample1719475216 - updated_at integerRequired
The permission policy last updated timestamp in epoch time.
formatint64Signed 64-bit integerexample1719475216
Show schema
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
Show schema
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
Show schema
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
- next_cursor string
Show schema
- 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_typeset tocontent, this defines the type of content the role's policies apply to:- The content type can be:
folder_idorcollection_id. - When assigning the role, provide the instance, e.g.
{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
- The content type can be:
- created_at integerRequired
Creation time of the policy in epoch time.
formatint64Signed 64-bit integer - updated_at integerRequired
Last updated time of the policy in epoch time.
formatint64Signed 64-bit integer
Show schema
- operation string
Specifies the operation to perform. Use
addto associate orremoveto 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_typeis "prodenv".example"975l29lz02jt0836fhwi" - policy_parameters object
Defines the content instance that the role applies to. Specify the content type (
folder_idorcollection_id) and its corresponding ID. For example,{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
Show schema
- 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
Show schema
- 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_typeis "prodenv".example"975l29lz02jt0836fhwi" - policy_parameters object
Defines the content instance that the role applies to. Specify the content type (
folder_idorcollection_id) and its corresponding ID. For example,{"folder_id":"asdfjkl12347890"}. This specification is passed to thepolicy_statement(Cedar).
Show schema
- 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.
Show schema
- 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.