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:

1
client.roles.updateCurrentEnvironmentPermissions(roleId, {
2
  positive_item_type_permissions: { add: [...], remove: [...] },
3
  negative_item_type_permissions: { add: [...], remove: [...] },
4
  positive_upload_permissions:    { add: [...], remove: [...] },
5
  negative_upload_permissions:    { add: [...], remove: [...] },
6
});

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

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

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

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

10
  // Append a negative entry forbidding `delete` to the current environment.
11
  const updated = await client.roles.updateCurrentEnvironmentPermissions(
12
    role.id,
13
    {
14
      negative_item_type_permissions: {
15
        add: [
16
          {
17
            action: "delete",
18
            on_creator: "anyone",
19
          },
20
        ],
21
      },
22
    },
23
  );
24

25
  console.log("Updated role:", updated.id, "—", updated.name);
26
  console.log(
27
    "Negative permissions now:",
28
    JSON.stringify(updated.negative_item_type_permissions, null, 2),
29
  );
30
}
31

32
run();

1
Updated role: 443075 — Power editor
2
Negative permissions now: [
3
  {
4
    "environment": "main",
5
    "item_type": null,
6
    "workflow": null,
7
    "on_stage": null,
8
    "to_stage": null,
9
    "action": "delete",
10
    "on_creator": "anyone",
11
    "localization_scope": null,
12
    "locale": null
13
  }
14
]

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

namestringOptional

The name of the role

Example:

"Editor"

can_edit_faviconbooleanOptional

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

can_edit_sitebooleanOptional

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

can_edit_schemabooleanOptional

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

can_manage_menubooleanOptional

Can customize content navigation bar

can_edit_environmentbooleanOptional

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_environmentsbooleanOptional

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_accessenumOptional

Specifies the environments the user can access

Example:

"primary_only"

allOptional

Grants access to all environments

primary_onlyOptional

Grants access exclusively to the primary environment

sandbox_onlyOptional

Grants access exclusively to sandbox environments

noneOptional

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

can_manage_usersbooleanOptional

Can create and edit roles and invite/remove collaborators

can_manage_shared_filtersbooleanOptional

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

can_manage_search_indexesbooleanOptional

Can create and edit search indexes

can_manage_upload_collectionsbooleanOptional

Can create and edit upload collections

can_manage_build_triggersbooleanOptional

Can create and edit build triggers

can_manage_webhooksbooleanOptional

Can create and edit webhooks

can_manage_environmentsbooleanOptional

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

can_manage_ssobooleanOptional

Can manage Single Sign-On settings

can_access_audit_logbooleanOptional

Can access Audit Log

can_manage_workflowsbooleanOptional

Can create and edit workflows

can_manage_access_tokensbooleanOptional

Can manage API tokens

can_perform_site_searchbooleanOptional

Can perform Site Search API calls

can_access_build_events_logbooleanOptional

Can access the build events log

can_access_search_index_events_logbooleanOptional

Can access the search index events log

positive_item_type_permissionsOptional

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

actionenumRequired

Permitted action

Example:

"read"

readOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"update"

updateOptional

publishOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"duplicate"

duplicateOptional

environmentstringRequired

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

Example:

"main"

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"delete"

deleteOptional

edit_creatorOptional

take_overOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"move_to_stage"

move_to_stageOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

negative_item_type_permissionsOptional

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

actionenumRequired

Permitted action

Example:

"read"

readOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"update"

updateOptional

publishOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"duplicate"

duplicateOptional

environmentstringRequired

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

Example:

"main"

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"delete"

deleteOptional

edit_creatorOptional

take_overOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"move_to_stage"

move_to_stageOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

positive_upload_permissionsOptional

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"update"

updateOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

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

not_localizedOptional

Non-localized content

upload_collectionstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"read"

readOptional

deleteOptional

edit_creatorOptional

replace_assetOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"move"

moveOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

move_to_upload_collectionstring, nullOptional

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

negative_upload_permissionsOptional

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"update"

updateOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

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

not_localizedOptional

Non-localized content

upload_collectionstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"read"

readOptional

deleteOptional

edit_creatorOptional

replace_assetOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"move"

moveOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

move_to_upload_collectionstring, nullOptional

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

positive_build_trigger_permissionsOptional

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_triggerstring, nullOptional

negative_build_trigger_permissionsOptional

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_triggerstring, nullOptional

positive_search_index_permissionsOptional

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_indexstring, nullOptional

negative_search_index_permissionsOptional

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_indexstring, nullOptional

meta.final_permissionsobjectOptional

The final set of permissions considering also inherited roles

can_edit_sitebooleanRequired

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

can_edit_faviconbooleanRequired

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

can_edit_schemabooleanRequired

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

can_manage_menubooleanRequired

Can customize content navigation bar

can_manage_usersbooleanRequired

Can create and edit roles and invite/remove collaborators

can_manage_environmentsbooleanRequired

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

can_manage_webhooksbooleanRequired

Can create and edit webhooks

environments_accessenumRequired

Specifies the environments the user can access

Example:

"primary_only"

allOptional

Grants access to all environments

primary_onlyOptional

Grants access exclusively to the primary environment

sandbox_onlyOptional

Grants access exclusively to sandbox environments

noneOptional

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

can_manage_ssobooleanRequired

Can manage Single Sign-On settings

can_access_audit_logbooleanRequired

Can access Audit Log

can_manage_workflowsbooleanRequired

Can create and edit workflows

can_edit_environmentbooleanRequired

can_promote_environmentsbooleanRequired

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_filtersbooleanRequired

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

can_manage_search_indexesbooleanRequired

Can create and edit search indexes

can_manage_build_triggersbooleanRequired

Can create and edit build triggers

can_manage_upload_collectionsbooleanRequired

Can create and edit upload collections

can_manage_access_tokensbooleanRequired

Can manage API tokens

can_perform_site_searchbooleanRequired

Can perform Site Search API calls

can_access_build_events_logbooleanRequired

Can access the build events log

can_access_search_index_events_logbooleanRequired

Can access the search index events log

positive_item_type_permissionsRequired

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

actionenumRequired

Permitted action

Example:

"read"

readOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"update"

updateOptional

publishOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"duplicate"

duplicateOptional

environmentstringRequired

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

Example:

"main"

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"delete"

deleteOptional

edit_creatorOptional

take_overOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"move_to_stage"

move_to_stageOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

negative_item_type_permissionsRequired

Type:Array<object>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

actionenumRequired

Permitted action

Example:

"read"

readOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"update"

updateOptional

publishOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

Content under a specific locale (locale must be defined)

not_localizedOptional

Non-localized content

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"duplicate"

duplicateOptional

environmentstringRequired

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

Example:

"main"

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"delete"

deleteOptional

edit_creatorOptional

take_overOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

actionenumRequired

Permitted action

Example:

"move_to_stage"

move_to_stageOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

item_typestring, nullOptional

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

workflowstring, nullOptional

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

on_stagestring, nullOptional

Restrict to records currently on a workflow stage.

to_stagestring, nullOptional

Restrict to moves towards a specific workflow stage.

positive_upload_permissionsRequired

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"update"

updateOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

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

not_localizedOptional

Non-localized content

upload_collectionstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"read"

readOptional

deleteOptional

edit_creatorOptional

replace_assetOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"move"

moveOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

move_to_upload_collectionstring, nullOptional

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

negative_upload_permissionsRequired

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>

actionenumRequired

Permitted action

Example:

"all"

allOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

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

Example:

"all"

allOptional

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"update"

updateOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

localization_scopeenumRequired

Permitted content scope

Example:

"all"

allOptional

Any content (localized/unlocalized)

localizedOptional

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

not_localizedOptional

Non-localized content

upload_collectionstring, nullOptional

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

localestring, nullOptional

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

Example:

"en"

actionenumRequired

Permitted action

Example:

"create"

createOptional

environmentstringRequired

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

Example:

"main"

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"read"

readOptional

deleteOptional

edit_creatorOptional

replace_assetOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

actionenumRequired

Permitted action

Example:

"move"

moveOptional

environmentstringRequired

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

Example:

"main"

on_creatorenumRequired

Permitted creator

Example:

"anyone"

anyoneOptional

Created by anyone

selfOptional

Created by the user itself

roleOptional

Created by a user with the same role

upload_collectionstring, nullOptional

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

move_to_upload_collectionstring, nullOptional

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

positive_build_trigger_permissionsRequired

Type:Array<object>

build_triggerstring, nullOptional

negative_build_trigger_permissionsRequired

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_triggerstring, nullOptional

positive_search_index_permissionsRequired

Type:Array<object>

search_indexstring, nullOptional

negative_search_index_permissionsRequired

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_indexstring, nullOptional

inherits_permissions_fromOptional

The roles from which this role inherits permissions

Type:Array<<a href="/docs/content-management-api/resources/role">ResourceLinkage<"role"></a>>

Returns

Returns a resource object of type role

Update a role

Safer permission edits with updateCurrentEnvironmentPermissions

Effects on bound credentials

Body parameters

Returns

Safer permission edits with `updateCurrentEnvironmentPermissions`