Content Management API > Role

Create a new role

Creates a new role in the project. The role is immediately assignable to collaborators, SSO users, and API tokens.

For the conceptual model — project-level vs content permissions, the discriminated-union shape of each positive_* / negative_* entry, and how inheritance is resolved — see the Role resource overview.

💡 Don't start from scratch

Most custom roles are easier to build by duplicating the closest-matching built-in role (e.g. Editor) and then editing the result, rather than constructing a permission tree from zero. Use this endpoint when you genuinely need a role that doesn't resemble any of the existing ones.

Body parameters

type string Required

Must be exactly "role".

attributes.name string Required

The name of the role

Example:

"Editor"

attributes.can_edit_favicon boolean Optional

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

attributes.can_edit_site boolean Optional

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

attributes.can_edit_schema boolean Optional

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

attributes.can_manage_menu boolean Optional

Can customize content navigation bar

attributes.can_edit_environment boolean Optional

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

attributes.can_promote_environments boolean Optional

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

attributes.environments_access enum Optional

Specifies the environments the user can access

Example:

"primary_only"

all Optional

Grants access to all environments

primary_only Optional

Grants access exclusively to the primary environment

sandbox_only Optional

Grants access exclusively to sandbox environments

none Optional

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

attributes.can_manage_users boolean Optional

Can create and edit roles and invite/remove collaborators

attributes.can_manage_shared_filters boolean Optional

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

attributes.can_manage_search_indexes boolean Optional

Can create and edit search indexes

attributes.can_manage_upload_collections boolean Optional

Can create and edit upload collections

attributes.can_manage_build_triggers boolean Optional

Can create and edit build triggers

attributes.can_manage_webhooks boolean Optional

Can create and edit webhooks

attributes.can_manage_environments boolean Optional

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

attributes.can_manage_sso boolean Optional

Can manage Single Sign-On settings

attributes.can_access_audit_log boolean Optional

Can access Audit Log

attributes.can_manage_workflows boolean Optional

Can create and edit workflows

attributes.can_manage_access_tokens boolean Optional

Can manage API tokens

attributes.can_perform_site_search boolean Optional

Can perform Site Search API calls

attributes.can_access_build_events_log boolean Optional

Can access the build events log

attributes.can_access_search_index_events_log boolean Optional

Can access the search index events log

attributes.positive_item_type_permissions Optional

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

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

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

action enum Required

Permitted action

Example:

"read"

read Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"update"

update Optional

publish Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"duplicate"

duplicate Optional

environment string Required

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

Example:

"main"

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"delete"

delete Optional

edit_creator Optional

take_over Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"move_to_stage"

move_to_stage Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

attributes.negative_item_type_permissions Optional

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

action enum Required

Permitted action

Example:

"read"

read Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"update"

update Optional

publish Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"duplicate"

duplicate Optional

environment string Required

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

Example:

"main"

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"delete"

delete Optional

edit_creator Optional

take_over Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"move_to_stage"

move_to_stage Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

attributes.positive_upload_permissions Optional

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

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"update"

update Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

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

not_localized Optional

Non-localized content

upload_collection string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"read"

read Optional

delete Optional

edit_creator Optional

replace_asset Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"move"

move Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

move_to_upload_collection string, null Optional

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

attributes.negative_upload_permissions Optional

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"update"

update Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

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

not_localized Optional

Non-localized content

upload_collection string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"read"

read Optional

delete Optional

edit_creator Optional

replace_asset Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"move"

move Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

move_to_upload_collection string, null Optional

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

attributes.positive_build_trigger_permissions Optional

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

Type: Array<object>

build_trigger string, null Optional

attributes.negative_build_trigger_permissions Optional

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

Type: Array<object>

build_trigger string, null Optional

attributes.positive_search_index_permissions Optional

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

Type: Array<object>

search_index string, null Optional

attributes.negative_search_index_permissions Optional

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

Type: Array<object>

search_index string, null Optional

meta.final_permissions object Required

The final set of permissions considering also inherited roles

can_edit_site boolean Required

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

can_edit_favicon boolean Required

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

can_edit_schema boolean Required

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

can_manage_menu boolean Required

Can customize content navigation bar

can_manage_users boolean Required

Can create and edit roles and invite/remove collaborators

can_manage_environments boolean Required

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

can_manage_webhooks boolean Required

Can create and edit webhooks

environments_access enum Required

Specifies the environments the user can access

Example:

"primary_only"

all Optional

Grants access to all environments

primary_only Optional

Grants access exclusively to the primary environment

sandbox_only Optional

Grants access exclusively to sandbox environments

none Optional

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

can_manage_sso boolean Required

Can manage Single Sign-On settings

can_access_audit_log boolean Required

Can access Audit Log

can_manage_workflows boolean Required

Can create and edit workflows

can_edit_environment boolean Required

can_promote_environments boolean Required

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

can_manage_shared_filters boolean Required

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

can_manage_search_indexes boolean Required

Can create and edit search indexes

can_manage_build_triggers boolean Required

Can create and edit build triggers

can_manage_upload_collections boolean Required

Can create and edit upload collections

can_manage_access_tokens boolean Required

Can manage API tokens

can_perform_site_search boolean Required

Can perform Site Search API calls

can_access_build_events_log boolean Required

Can access the build events log

can_access_search_index_events_log boolean Required

Can access the search index events log

positive_item_type_permissions Required

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

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

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

action enum Required

Permitted action

Example:

"read"

read Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"update"

update Optional

publish Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"duplicate"

duplicate Optional

environment string Required

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

Example:

"main"

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"delete"

delete Optional

edit_creator Optional

take_over Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"move_to_stage"

move_to_stage Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

negative_item_type_permissions Required

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

action enum Required

Permitted action

Example:

"read"

read Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"update"

update Optional

publish Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Content under a specific locale (locale must be defined)

not_localized Optional

Non-localized content

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"duplicate"

duplicate Optional

environment string Required

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

Example:

"main"

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"delete"

delete Optional

edit_creator Optional

take_over Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

action enum Required

Permitted action

Example:

"move_to_stage"

move_to_stage Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

item_type string, null Optional

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

workflow string, null Optional

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

on_stage string, null Optional

Restrict to records currently on a workflow stage.

to_stage string, null Optional

Restrict to moves towards a specific workflow stage.

positive_upload_permissions Required

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

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"update"

update Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

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

not_localized Optional

Non-localized content

upload_collection string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"read"

read Optional

delete Optional

edit_creator Optional

replace_asset Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"move"

move Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

move_to_upload_collection string, null Optional

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

negative_upload_permissions Required

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

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

Example:

"all"

all Optional

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"update"

update Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

localization_scope enum Required

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

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

not_localized Optional

Non-localized content

upload_collection string, null Optional

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

locale string, null Optional

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

Example:

"en"

action enum Required

Permitted action

Example:

"create"

create Optional

environment string Required

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

Example:

"main"

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"read"

read Optional

delete Optional

edit_creator Optional

replace_asset Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

action enum Required

Permitted action

Example:

"move"

move Optional

environment string Required

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

Example:

"main"

on_creator enum Required

Permitted creator

Example:

"anyone"

anyone Optional

Created by anyone

self Optional

Created by the user itself

role Optional

Created by a user with the same role

upload_collection string, null Optional

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

move_to_upload_collection string, null Optional

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

positive_build_trigger_permissions Required

Type: Array<object>

build_trigger string, null Optional

negative_build_trigger_permissions Required

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

Type: Array<object>

build_trigger string, null Optional

positive_search_index_permissions Required

Type: Array<object>

search_index string, null Optional

negative_search_index_permissions Required

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

Type: Array<object>

search_index string, null Optional

relationships.inherits_permissions_from.data Optional

The roles from which this role inherits permissions

Type: Array<ResourceLinkage<"role">>

Returns

Returns a resource object of type role.

Examples

1
POST https://site-api.datocms.com/roles HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "role",
10
    "attributes": {
11
      "name": "Editor"
12
    }
13
  }
14
}

1
curl -g 'https://site-api.datocms.com/roles' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"role","attributes":{"name":"Editor"}}}'

1
await fetch("https://site-api.datocms.com/roles", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: { type: "role", attributes: { name: "Editor" } },
11
  }),
12
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "role",
10
    "id": "34",
11
    "attributes": {
12
      "name": "Editor",
13
      "can_edit_site": true,
14
      "can_edit_favicon": true,
15
      "can_edit_schema": true,
16
      "can_manage_menu": true,
17
      "can_manage_users": true,
18
      "can_manage_shared_filters": true,
19
      "can_manage_search_indexes": true,
20
      "can_manage_upload_collections": true,
21
      "can_manage_environments": true,
22
      "can_manage_webhooks": true,
23
      "environments_access": "primary_only",
24
      "can_manage_sso": true,
25
      "can_access_audit_log": true,
26
      "can_manage_workflows": true,
27
      "can_edit_environment": true,
28
      "can_promote_environments": true,
29
      "can_manage_build_triggers": true,
30
      "can_manage_access_tokens": true,
31
      "can_perform_site_search": true,
32
      "can_access_build_events_log": true,
33
      "can_access_search_index_events_log": true,
34
      "positive_item_type_permissions": [
35
        {
36
          "action": "all",
37
          "environment": "main",
38
          "on_creator": "anyone",
39
          "localization_scope": "all"
40
        },
41
        {
42
          "action": "read",
43
          "environment": "main",
44
          "on_creator": "anyone"
45
        },
46
        {
47
          "action": "create",
48
          "environment": "main",
49
          "localization_scope": "all"
50
        },
51
        {
52
          "action": "update",
53
          "environment": "main",
54
          "on_creator": "anyone",
55
          "localization_scope": "all"
56
        },
57
        {
58
          "action": "duplicate",
59
          "environment": "main"
60
        },
61
        {
62
          "action": "delete",
63
          "environment": "main",
64
          "on_creator": "anyone"
65
        },
66
        {
67
          "action": "move_to_stage",
68
          "environment": "main",
69
          "on_creator": "anyone"
70
        }
71
      ],
72
      "negative_item_type_permissions": [
73
        {
74
          "action": "all",
75
          "environment": "main",
76
          "on_creator": "anyone",
77
          "localization_scope": "all"
78
        },
79
        {
80
          "action": "read",
81
          "environment": "main",
82
          "on_creator": "anyone"
83
        },
84
        {
85
          "action": "create",
86
          "environment": "main",
87
          "localization_scope": "all"
88
        },
89
        {
90
          "action": "update",
91
          "environment": "main",
92
          "on_creator": "anyone",
93
          "localization_scope": "all"
94
        },
95
        {
96
          "action": "duplicate",
97
          "environment": "main"
98
        },
99
        {
100
          "action": "delete",
101
          "environment": "main",
102
          "on_creator": "anyone"
103
        },
104
        {
105
          "action": "move_to_stage",
106
          "environment": "main",
107
          "on_creator": "anyone"
108
        }
109
      ],
110
      "positive_upload_permissions": [
111
        {
112
          "action": "all",
113
          "environment": "main",
114
          "on_creator": "anyone",
115
          "localization_scope": "all"
116
        },
117
        {
118
          "action": "update",
119
          "environment": "main",
120
          "on_creator": "anyone",
121
          "localization_scope": "all"
122
        },
123
        {
124
          "action": "create",
125
          "environment": "main"
126
        },
127
        {
128
          "action": "read",
129
          "environment": "main",
130
          "on_creator": "anyone"
131
        },
132
        {
133
          "action": "move",
134
          "environment": "main",
135
          "on_creator": "anyone"
136
        }
137
      ],
138
      "negative_upload_permissions": [
139
        {
140
          "action": "all",
141
          "environment": "main",
142
          "on_creator": "anyone",
143
          "localization_scope": "all"
144
        },
145
        {
146
          "action": "update",
147
          "environment": "main",
148
          "on_creator": "anyone",
149
          "localization_scope": "all"
150
        },
151
        {
152
          "action": "create",
153
          "environment": "main"
154
        },
155
        {
156
          "action": "read",
157
          "environment": "main",
158
          "on_creator": "anyone"
159
        },
160
        {
161
          "action": "move",
162
          "environment": "main",
163
          "on_creator": "anyone"
164
        }
165
      ],
166
      "positive_build_trigger_permissions": [
167
        {}
168
      ],
169
      "negative_build_trigger_permissions": [
170
        {}
171
      ],
172
      "positive_search_index_permissions": [
173
        {}
174
      ],
175
      "negative_search_index_permissions": [
176
        {}
177
      ]
178
    },
179
    "relationships": {
180
      "inherits_permissions_from": {
181
        "data": [
182
          {
183
            "type": "role",
184
            "id": "34"
185
          }
186
        ]
187
      }
188
    },
189
    "meta": {
190
      "final_permissions": {
191
        "can_edit_site": true,
192
        "can_edit_favicon": true,
193
        "can_edit_schema": true,
194
        "can_manage_menu": true,
195
        "can_manage_users": true,
196
        "can_manage_environments": true,
197
        "can_manage_webhooks": true,
198
        "environments_access": "primary_only",
199
        "can_manage_sso": true,
200
        "can_access_audit_log": true,
201
        "can_manage_workflows": true,
202
        "can_edit_environment": true,
203
        "can_promote_environments": true,
204
        "can_manage_shared_filters": true,
205
        "can_manage_search_indexes": true,
206
        "can_manage_build_triggers": true,
207
        "can_manage_upload_collections": true,
208
        "can_manage_access_tokens": true,
209
        "can_perform_site_search": true,
210
        "can_access_build_events_log": true,
211
        "can_access_search_index_events_log": true,
212
        "positive_item_type_permissions": [
213
          {
214
            "action": "all",
215
            "environment": "main",
216
            "on_creator": "anyone",
217
            "localization_scope": "all"
218
          },
219
          {
220
            "action": "read",
221
            "environment": "main",
222
            "on_creator": "anyone"
223
          },
224
          {
225
            "action": "create",
226
            "environment": "main",
227
            "localization_scope": "all"
228
          },
229
          {
230
            "action": "update",
231
            "environment": "main",
232
            "on_creator": "anyone",
233
            "localization_scope": "all"
234
          },
235
          {
236
            "action": "duplicate",
237
            "environment": "main"
238
          },
239
          {
240
            "action": "delete",
241
            "environment": "main",
242
            "on_creator": "anyone"
243
          },
244
          {
245
            "action": "move_to_stage",
246
            "environment": "main",
247
            "on_creator": "anyone"
248
          }
249
        ],
250
        "negative_item_type_permissions": [
251
          {
252
            "action": "all",
253
            "environment": "main",
254
            "on_creator": "anyone",
255
            "localization_scope": "all"
256
          },
257
          {
258
            "action": "read",
259
            "environment": "main",
260
            "on_creator": "anyone"
261
          },
262
          {
263
            "action": "create",
264
            "environment": "main",
265
            "localization_scope": "all"
266
          },
267
          {
268
            "action": "update",
269
            "environment": "main",
270
            "on_creator": "anyone",
271
            "localization_scope": "all"
272
          },
273
          {
274
            "action": "duplicate",
275
            "environment": "main"
276
          },
277
          {
278
            "action": "delete",
279
            "environment": "main",
280
            "on_creator": "anyone"
281
          },
282
          {
283
            "action": "move_to_stage",
284
            "environment": "main",
285
            "on_creator": "anyone"
286
          }
287
        ],
288
        "positive_upload_permissions": [
289
          {
290
            "action": "all",
291
            "environment": "main",
292
            "on_creator": "anyone",
293
            "localization_scope": "all"
294
          },
295
          {
296
            "action": "update",
297
            "environment": "main",
298
            "on_creator": "anyone",
299
            "localization_scope": "all"
300
          },
301
          {
302
            "action": "create",
303
            "environment": "main"
304
          },
305
          {
306
            "action": "read",
307
            "environment": "main",
308
            "on_creator": "anyone"
309
          },
310
          {
311
            "action": "move",
312
            "environment": "main",
313
            "on_creator": "anyone"
314
          }
315
        ],
316
        "negative_upload_permissions": [
317
          {
318
            "action": "all",
319
            "environment": "main",
320
            "on_creator": "anyone",
321
            "localization_scope": "all"
322
          },
323
          {
324
            "action": "update",
325
            "environment": "main",
326
            "on_creator": "anyone",
327
            "localization_scope": "all"
328
          },
329
          {
330
            "action": "create",
331
            "environment": "main"
332
          },
333
          {
334
            "action": "read",
335
            "environment": "main",
336
            "on_creator": "anyone"
337
          },
338
          {
339
            "action": "move",
340
            "environment": "main",
341
            "on_creator": "anyone"
342
          }
343
        ],
344
        "positive_build_trigger_permissions": [
345
          {}
346
        ],
347
        "negative_build_trigger_permissions": [
348
          {}
349
        ],
350
        "positive_search_index_permissions": [
351
          {}
352
        ],
353
        "negative_search_index_permissions": [
354
          {}
355
        ]
356
      }
357
    }
358
  }
359
}