Show examples in:
Javascript HTTP
Sections
Endpoint info
Available examples
Content Management API > Role

Update a role

Updates an existing role. Any attribute or relationship omitted from the payload is left unchanged.

The full positive_* / negative_* permission arrays are replaced wholesale when sent — there is no "patch a single permission entry" operation on this endpoint. Read the role first and forward the entries you don't want to change, or use the SDK helper described below.

Safer permission edits with updateCurrentEnvironmentPermissions

For records and uploads in the current environment, the SDK ships a higher-level helper:

client.roles.updateCurrentEnvironmentPermissions(roleId, {
  positive_item_type_permissions: { add: [...], remove: [...] },
  negative_item_type_permissions: { add: [...], remove: [...] },
  positive_upload_permissions:    { add: [...], remove: [...] },
  negative_upload_permissions:    { add: [...], remove: [...] },
});

It reads the role, applies the diff against the entries scoped to the current environment, and forwards the merged arrays — so individual entries can be added or removed without rewriting the surrounding state. Build trigger and search index permissions, and entries scoped to other environments, still need a direct client.roles.update(...) call.

Subtract a single action from a role that already grants action: "all". The fix is to append a negative_item_type_permissions entry naming the action to take away — the existing positive all entry stays, and the formula (positive_*) − negative_* resolves to "everything but delete".

import { buildClient } from "@datocms/cma-client-node";


async function run() {
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });


  // Look up the existing "Power editor" role to patch.
  const allRoles = await client.roles.list();
  const role = allRoles.find((candidate) => candidate.name === "Power editor")!;


  // Append a negative entry forbidding `delete` to the current environment.
  const updated = await client.roles.updateCurrentEnvironmentPermissions(
    role.id,
    {
      negative_item_type_permissions: {
        add: [
          {
            action: "delete",
            on_creator: "anyone",
          },
        ],
      },
    },
  );


  console.log("Updated role:", updated.id, "—", updated.name);
  console.log(
    "Negative permissions now:",
    JSON.stringify(updated.negative_item_type_permissions, null, 2),
  );
}


run();
Updated role: 443075 — Power editor
Negative permissions now: [
  {
    "environment": "main",
    "item_type": null,
    "workflow": null,
    "on_stage": null,
    "to_stage": null,
    "action": "delete",
    "on_creator": "anyone",
    "localization_scope": null,
    "locale": null
  }
]

Effects on bound credentials

Changes take effect immediately for every credential bound to this role: collaborators, SSO users, and API tokens will see new requests evaluated against the updated meta.final_permissions on their next call.

Body parameters

name string Optional

The name of the role

Example: "Editor"
can_edit_favicon boolean Optional

Can edit favicon, global SEO settings and no-index policy

can_edit_site boolean Optional

Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings)

can_edit_schema boolean Optional

Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins

can_manage_menu boolean Optional

Can customize content navigation bar

can_edit_environment boolean Optional

Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is not about creating or switching environments — see can_manage_environments for that, and environments_access for which environments this role can enter at all.

can_promote_environments boolean Optional

Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from can_manage_environments, which covers creating/forking/deleting sandboxes.

environments_access enum Optional

Specifies the environments the user can access

Example: "primary_only"
all Optional

Grants access to all environments

primary_only Optional

Grants access exclusively to the primary environment

sandbox_only Optional

Grants access exclusively to sandbox environments

none Optional

No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
can_manage_users boolean Optional

Can create and edit roles and invite/remove collaborators

can_manage_shared_filters boolean Optional

Can create and edit shared filters (both for models and the media area)

can_manage_search_indexes boolean Optional

Can create and edit search indexes

can_manage_upload_collections boolean Optional

Can create and edit upload collections

can_manage_build_triggers boolean Optional

Can create and edit build triggers

can_manage_webhooks boolean Optional

Can create and edit webhooks

can_manage_environments boolean Optional

Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by can_promote_environments.

can_manage_sso boolean Optional

Can manage Single Sign-On settings

can_access_audit_log boolean Optional

Can access Audit Log

can_manage_workflows boolean Optional

Can create and edit workflows

can_manage_access_tokens boolean Optional

Can manage API tokens

can_perform_site_search boolean Optional

Can perform Site Search API calls

can_access_build_events_log boolean Optional

Can access the build events log

can_access_search_index_events_log boolean Optional

Can access the search index events log

positive_item_type_permissions Optional

Allowed actions on a model (or all) for a role.

The shape of each entry depends on the action (discriminated union). Idiomatic recipes:

  • To grant every action, use a single action: "all" entry with localization_scope: "all".
  • To grant a subset (e.g. create+read+update but not delete), prefer a single action: "all" entry plus negative_item_type_permissions entries for the actions to exclude — instead of listing each allowed action separately.
Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
action enum Required

Permitted action

Example: "read"
read Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "update"
update Optional
publish Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "duplicate"
duplicate Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "delete"
delete Optional
edit_creator Optional
take_over Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "move_to_stage"
move_to_stage Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
negative_item_type_permissions Optional

Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive action: "all" entry to subtract specific actions (e.g. forbid delete).

Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
action enum Required

Permitted action

Example: "read"
read Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "update"
update Optional
publish Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "duplicate"
duplicate Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "delete"
delete Optional
edit_creator Optional
take_over Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "move_to_stage"
move_to_stage Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
positive_upload_permissions Optional

Allowed actions on uploads (or all) for a role.

The shape of each entry depends on the action (discriminated union). To grant a subset, prefer a single action: "all" entry plus negative_upload_permissions entries for the actions to exclude.

Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "update"
update Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in a specific locale (locale must be defined)

not_localized Optional

Non-localized content
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "read"
read Optional
delete Optional
edit_creator Optional
replace_asset Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "move"
move Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

move_to_upload_collection string, null Optional

Restricts the destination upload collection of the move action. When null, any destination is allowed.
negative_upload_permissions Optional

Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive action: "all" entry to subtract specific actions.

Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "update"
update Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in a specific locale (locale must be defined)

not_localized Optional

Non-localized content
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "read"
read Optional
delete Optional
edit_creator Optional
replace_asset Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "move"
move Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

move_to_upload_collection string, null Optional

Restricts the destination upload collection of the move action. When null, any destination is allowed.
positive_build_trigger_permissions Optional

Build triggers this role is allowed to manually fire. An entry with build_trigger: null covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by can_manage_build_triggers.

Type: Array<object>
build_trigger string, null Optional
negative_build_trigger_permissions Optional

Build triggers this role is forbidden from manually firing. Negative entries take precedence over positive ones; pair with a build_trigger: null positive entry to allow all-but-N.

Type: Array<object>
build_trigger string, null Optional
positive_search_index_permissions Optional

Search indexes this role is allowed to manually re-index. An entry with search_index: null covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by can_manage_search_indexes.

Type: Array<object>
search_index string, null Optional
negative_search_index_permissions Optional

Search indexes this role is forbidden from manually re-indexing. Negative entries take precedence over positive ones; pair with a search_index: null positive entry to allow all-but-N.

Type: Array<object>
search_index string, null Optional
meta.final_permissions object Optional

The final set of permissions considering also inherited roles

can_edit_site boolean Required

Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings)

can_edit_favicon boolean Required

Can edit favicon, global SEO settings and no-index policy

can_edit_schema boolean Required

Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins

can_manage_menu boolean Required

Can customize content navigation bar

can_manage_users boolean Required

Can create and edit roles and invite/remove collaborators

can_manage_environments boolean Required

Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by can_promote_environments.

can_manage_webhooks boolean Required

Can create and edit webhooks

environments_access enum Required

Specifies the environments the user can access

Example: "primary_only"
all Optional

Grants access to all environments

primary_only Optional

Grants access exclusively to the primary environment

sandbox_only Optional

Grants access exclusively to sandbox environments

none Optional

No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
can_manage_sso boolean Required

Can manage Single Sign-On settings

can_access_audit_log boolean Required

Can access Audit Log

can_manage_workflows boolean Required

Can create and edit workflows

can_edit_environment boolean Required

Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is not about creating or switching environments — see can_manage_environments for that, and environments_access for which environments this role can enter at all.

can_promote_environments boolean Required

Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from can_manage_environments, which covers creating/forking/deleting sandboxes.

can_manage_shared_filters boolean Required

Can create and edit shared filters (both for models and the media area)

can_manage_search_indexes boolean Required

Can create and edit search indexes

can_manage_build_triggers boolean Required

Can create and edit build triggers

can_manage_upload_collections boolean Required

Can create and edit upload collections

can_manage_access_tokens boolean Required

Can manage API tokens

can_perform_site_search boolean Required

Can perform Site Search API calls

can_access_build_events_log boolean Required

Can access the build events log

can_access_search_index_events_log boolean Required

Can access the search index events log

positive_item_type_permissions Required

Allowed actions on a model (or all) for a role.

The shape of each entry depends on the action (discriminated union). Idiomatic recipes:

  • To grant every action, use a single action: "all" entry with localization_scope: "all".
  • To grant a subset (e.g. create+read+update but not delete), prefer a single action: "all" entry plus negative_item_type_permissions entries for the actions to exclude — instead of listing each allowed action separately.
Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
action enum Required

Permitted action

Example: "read"
read Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "update"
update Optional
publish Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "duplicate"
duplicate Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "delete"
delete Optional
edit_creator Optional
take_over Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "move_to_stage"
move_to_stage Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
negative_item_type_permissions Required

Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive action: "all" entry to subtract specific actions (e.g. forbid delete).

Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
action enum Required

Permitted action

Example: "read"
read Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "update"
update Optional
publish Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "duplicate"
duplicate Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "delete"
delete Optional
edit_creator Optional
take_over Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.
action enum Required

Permitted action

Example: "move_to_stage"
move_to_stage Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
item_type string, null Optional

Restricts the permission to a specific model. When null, the permission applies to all models.

workflow string, null Optional

Restricts the permission to records associated with a specific workflow. Mutually exclusive with item_type.

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.
positive_upload_permissions Required

Allowed actions on uploads (or all) for a role.

The shape of each entry depends on the action (discriminated union). To grant a subset, prefer a single action: "all" entry plus negative_upload_permissions entries for the actions to exclude.

Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "update"
update Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in a specific locale (locale must be defined)

not_localized Optional

Non-localized content
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "read"
read Optional
delete Optional
edit_creator Optional
replace_asset Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "move"
move Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

move_to_upload_collection string, null Optional

Restricts the destination upload collection of the move action. When null, any destination is allowed.
negative_upload_permissions Required

Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive action: "all" entry to subtract specific actions.

Type: Array<object>
action enum Required

Permitted action

Example: "all"
all Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

For action: "all" this must be "all".

Example: "all"
all Optional
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "update"
update Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
localization_scope enum Required

Permitted content scope

Example: "all"
all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in a specific locale (locale must be defined)

not_localized Optional

Non-localized content
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

locale string, null Optional

Required (non-null) when localization_scope is "localized"; must be omitted otherwise.

Example: "en"
action enum Required

Permitted action

Example: "create"
create Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "read"
read Optional
delete Optional
edit_creator Optional
replace_asset Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.
action enum Required

Permitted action

Example: "move"
move Optional
environment string Required

ID of environment. Can only contain lowercase letters, numbers and dashes

Example: "main"
on_creator enum Required

Permitted creator

Example: "anyone"
anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role
upload_collection string, null Optional

Restricts the permission to a specific upload collection. When null, the permission applies to all collections.

move_to_upload_collection string, null Optional

Restricts the destination upload collection of the move action. When null, any destination is allowed.
positive_build_trigger_permissions Required

Build triggers this role is allowed to manually fire. An entry with build_trigger: null covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by can_manage_build_triggers.

Type: Array<object>
build_trigger string, null Optional
negative_build_trigger_permissions Required

Build triggers this role is forbidden from manually firing. Negative entries take precedence over positive ones; pair with a build_trigger: null positive entry to allow all-but-N.

Type: Array<object>
build_trigger string, null Optional
positive_search_index_permissions Required

Search indexes this role is allowed to manually re-index. An entry with search_index: null covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by can_manage_search_indexes.

Type: Array<object>
search_index string, null Optional
negative_search_index_permissions Required

Search indexes this role is forbidden from manually re-indexing. Negative entries take precedence over positive ones; pair with a search_index: null positive entry to allow all-but-N.

Type: Array<object>
search_index string, null Optional
inherits_permissions_from Optional

The roles from which this role inherits permissions

Returns

Returns a resource object of type role

Did this doc help you?
Yes
No
Would you like to add more information?
Optional
To receive further updates or address your feedback, kindly share your email address with us.
Optional

If you need a reply, please contact support instead.

Need help?
Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.