# 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:
```ts
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.
###### Example Subtract one action from a role that grants "all"
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`".
Code
```javascript
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();
```
Returned output
```javascript
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`**
- Optional
- Type: string
- Example: `"Editor"`
The name of the role
**`can_edit_favicon`**
- Optional
- Type: boolean
Can edit favicon, global SEO settings and no-index policy
**`can_edit_site`**
- Optional
- Type: boolean
Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings)
**`can_edit_schema`**
- Optional
- Type: boolean
Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins
**`can_manage_menu`**
- Optional
- Type: boolean
Can customize content navigation bar
**`can_edit_environment`**
- Optional
- Type: boolean
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`**
- Optional
- Type: boolean
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`**
- Optional
- Type: enum
- Example: `"primary_only"`
Specifies the environments the user can access
Show enum values
**`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`**
- Optional
- Type: boolean
Can create and edit roles and invite/remove collaborators
**`can_manage_shared_filters`**
- Optional
- Type: boolean
Can create and edit shared filters (both for models and the media area)
**`can_manage_search_indexes`**
- Optional
- Type: boolean
Can create and edit search indexes
**`can_manage_upload_collections`**
- Optional
- Type: boolean
Can create and edit upload collections
**`can_manage_build_triggers`**
- Optional
- Type: boolean
Can create and edit build triggers
**`can_manage_webhooks`**
- Optional
- Type: boolean
Can create and edit webhooks
**`can_manage_environments`**
- Optional
- Type: boolean
Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`.
**`can_manage_sso`**
- Optional
- Type: boolean
Can manage Single Sign-On settings
**`can_access_audit_log`**
- Optional
- Type: boolean
Can access Audit Log
**`can_manage_workflows`**
- Optional
- Type: boolean
Can create and edit workflows
**`can_manage_access_tokens`**
- Optional
- Type: boolean
Can manage API tokens
**`can_perform_site_search`**
- Optional
- Type: boolean
Can perform Site Search API calls
**`can_access_build_events_log`**
- Optional
- Type: boolean
Can access the build events log
**`can_access_search_index_events_log`**
- Optional
- Type: boolean
Can access the search index events log
**`positive_item_type_permissions`**
- Optional
- Type: Array\
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.
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
Show object format when action is "read"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`publish`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate"
**`action`**
- Required
- Type: enum
- Example: `"duplicate"`
Permitted action
Show enum values
**`duplicate`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over"
**`action`**
- Required
- Type: enum
- Example: `"delete"`
Permitted action
Show enum values
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`take_over`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage"
**`action`**
- Required
- Type: enum
- Example: `"move_to_stage"`
Permitted action
Show enum values
**`move_to_stage`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`**
- Optional
- Type: Array\
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`).
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
Show object format when action is "read"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`publish`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate"
**`action`**
- Required
- Type: enum
- Example: `"duplicate"`
Permitted action
Show enum values
**`duplicate`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over"
**`action`**
- Required
- Type: enum
- Example: `"delete"`
Permitted action
Show enum values
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`take_over`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage"
**`action`**
- Required
- Type: enum
- Example: `"move_to_stage"`
Permitted action
Show enum values
**`move_to_stage`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`**
- Optional
- Type: Array\
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.
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`replace_asset`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move"
**`action`**
- Required
- Type: enum
- Example: `"move"`
Permitted action
Show enum values
**`move`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`move_to_upload_collection`**
- Optional
- Type: string, null
Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`**
- Optional
- Type: Array\
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.
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`replace_asset`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move"
**`action`**
- Required
- Type: enum
- Example: `"move"`
Permitted action
Show enum values
**`move`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`move_to_upload_collection`**
- Optional
- Type: string, null
Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`**
- Optional
- Type: Array\
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`.
Show objects format inside array
**`build_trigger`**
- Optional
- Type: string, null
**`negative_build_trigger_permissions`**
- Optional
- Type: Array\
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.
Show objects format inside array
**`build_trigger`**
- Optional
- Type: string, null
**`positive_search_index_permissions`**
- Optional
- Type: Array\
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`.
Show objects format inside array
**`search_index`**
- Optional
- Type: string, null
**`negative_search_index_permissions`**
- Optional
- Type: Array\
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.
Show objects format inside array
**`search_index`**
- Optional
- Type: string, null
**`meta.final_permissions`**
- Optional
- Type: object
The final set of permissions considering also inherited roles
Show object format
**`can_edit_site`**
- Required
- Type: boolean
Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings)
**`can_edit_favicon`**
- Required
- Type: boolean
Can edit favicon, global SEO settings and no-index policy
**`can_edit_schema`**
- Required
- Type: boolean
Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins
**`can_manage_menu`**
- Required
- Type: boolean
Can customize content navigation bar
**`can_manage_users`**
- Required
- Type: boolean
Can create and edit roles and invite/remove collaborators
**`can_manage_environments`**
- Required
- Type: boolean
Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`.
**`can_manage_webhooks`**
- Required
- Type: boolean
Can create and edit webhooks
**`environments_access`**
- Required
- Type: enum
- Example: `"primary_only"`
Specifies the environments the user can access
Show enum values
**`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`**
- Required
- Type: boolean
Can manage Single Sign-On settings
**`can_access_audit_log`**
- Required
- Type: boolean
Can access Audit Log
**`can_manage_workflows`**
- Required
- Type: boolean
Can create and edit workflows
**`can_edit_environment`**
- Required
- Type: boolean
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`**
- Required
- Type: boolean
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`**
- Required
- Type: boolean
Can create and edit shared filters (both for models and the media area)
**`can_manage_search_indexes`**
- Required
- Type: boolean
Can create and edit search indexes
**`can_manage_build_triggers`**
- Required
- Type: boolean
Can create and edit build triggers
**`can_manage_upload_collections`**
- Required
- Type: boolean
Can create and edit upload collections
**`can_manage_access_tokens`**
- Required
- Type: boolean
Can manage API tokens
**`can_perform_site_search`**
- Required
- Type: boolean
Can perform Site Search API calls
**`can_access_build_events_log`**
- Required
- Type: boolean
Can access the build events log
**`can_access_search_index_events_log`**
- Required
- Type: boolean
Can access the search index events log
**`positive_item_type_permissions`**
- Required
- Type: Array\
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.
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
Show object format when action is "read"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`publish`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate"
**`action`**
- Required
- Type: enum
- Example: `"duplicate"`
Permitted action
Show enum values
**`duplicate`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over"
**`action`**
- Required
- Type: enum
- Example: `"delete"`
Permitted action
Show enum values
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`take_over`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage"
**`action`**
- Required
- Type: enum
- Example: `"move_to_stage"`
Permitted action
Show enum values
**`move_to_stage`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`**
- Required
- Type: Array\
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`).
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
Show object format when action is "read"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`publish`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate"
**`action`**
- Required
- Type: enum
- Example: `"duplicate"`
Permitted action
Show enum values
**`duplicate`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over"
**`action`**
- Required
- Type: enum
- Example: `"delete"`
Permitted action
Show enum values
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`take_over`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage"
**`action`**
- Required
- Type: enum
- Example: `"move_to_stage"`
Permitted action
Show enum values
**`move_to_stage`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`item_type`**
- Optional
- Type: string, null
Restricts the permission to a specific model. When `null`, the permission applies to all models.
**`workflow`**
- Optional
- Type: string, null
Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
**`on_stage`**
- Optional
- Type: string, null
Restrict to records currently on a workflow stage.
**`to_stage`**
- Optional
- Type: string, null
Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`**
- Required
- Type: Array\
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.
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`replace_asset`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move"
**`action`**
- Required
- Type: enum
- Example: `"move"`
Permitted action
Show enum values
**`move`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`move_to_upload_collection`**
- Optional
- Type: string, null
Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`**
- Required
- Type: Array\
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.
Show object format when action is "all"
**`action`**
- Required
- Type: enum
- Example: `"all"`
Permitted action
Show enum values
**`all`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
For `action: "all"` this must be `"all"`.
Show enum values
**`all`**
- Optional
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update"
**`action`**
- Required
- Type: enum
- Example: `"update"`
Permitted action
Show enum values
**`update`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`localization_scope`**
- Required
- Type: enum
- Example: `"all"`
Permitted content scope
Show enum values
**`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`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`locale`**
- Optional
- Type: string, null
- Example: `"en"`
Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create"
**`action`**
- Required
- Type: enum
- Example: `"create"`
Permitted action
Show enum values
**`create`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset"
**`action`**
- Required
- Type: enum
- Example: `"read"`
Permitted action
Show enum values
**`read`**
- Optional
**`delete`**
- Optional
**`edit_creator`**
- Optional
**`replace_asset`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move"
**`action`**
- Required
- Type: enum
- Example: `"move"`
Permitted action
Show enum values
**`move`**
- Optional
**`environment`**
- Required
- Type: string
- Example: `"main"`
ID of environment. Can only contain lowercase letters, numbers and dashes
**`on_creator`**
- Required
- Type: enum
- Example: `"anyone"`
Permitted creator
Show enum values
**`anyone`**
- Optional
Created by anyone
**`self`**
- Optional
Created by the user itself
**`role`**
- Optional
Created by a user with the same role
**`upload_collection`**
- Optional
- Type: string, null
Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
**`move_to_upload_collection`**
- Optional
- Type: string, null
Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`**
- Required
- Type: Array\
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`.
Show objects format inside array
**`build_trigger`**
- Optional
- Type: string, null
**`negative_build_trigger_permissions`**
- Required
- Type: Array\
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.
Show objects format inside array
**`build_trigger`**
- Optional
- Type: string, null
**`positive_search_index_permissions`**
- Required
- Type: Array\
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`.
Show objects format inside array
**`search_index`**
- Optional
- Type: string, null
**`negative_search_index_permissions`**
- Required
- Type: Array\
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.
Show objects format inside array
**`search_index`**
- Optional
- Type: string, null
**`inherits_permissions_from`**
- Optional
- Type: Array<[ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md)>
The roles from which this role inherits permissions
## Returns
Returns a resource object of type [role](https://www.datocms.com/docs/content-management-api/resources/role.md)
## Related content in "Content Management API"
- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)
- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)
- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)
- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)
- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [CMA Technical Limits & Rate Limits](https://www.datocms.com/docs/content-management-api/technical-limits.md)
- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)
- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)
- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)
- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)
- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)
- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)
- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)
- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)
- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)
- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)
- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)
- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)
- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)
- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)
- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)
- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)
- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)
- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)
- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)
- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)
- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)
- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)
- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)
- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)
- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)
- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)
- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)
- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)
- [Create a new role](https://www.datocms.com/docs/content-management-api/resources/role/create.md)
- [Update a role](https://www.datocms.com/docs/content-management-api/resources/role/update.md)
- [List all roles](https://www.datocms.com/docs/content-management-api/resources/role/instances.md)
- [Retrieve a role](https://www.datocms.com/docs/content-management-api/resources/role/self.md)
- [Delete a role](https://www.datocms.com/docs/content-management-api/resources/role/destroy.md)
- [Duplicate a role](https://www.datocms.com/docs/content-management-api/resources/role/duplicate.md)
- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)
- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)
- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)
- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)
- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)
- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)
- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)
- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)
- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)
- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)
- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)
- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)