Show examples in:

Endpoint info

Returns

Available examples

Basic example

Content Management API > Role

Update a role

Body parameters

type string Required

Must be exactly "role".

attributes.name string Optional

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 global properties

attributes.can_edit_schema boolean Optional

Can create/edit models and plugins

attributes.can_manage_menu boolean Optional

Can customize content navigation bar

attributes.can_edit_environment boolean Optional

Can change locales, timezone and UI theme

attributes.can_promote_environments boolean Optional

Can promote environments to primary and manage maintenance mode

attributes.environments_access enum Optional

Specifies the environments the user can access

Example:

"primary_only"

all Optional

Can access all environments

primary_only Optional

Can access primary environment only

sandbox_only Optional

Can access sandbox environments only

attributes.can_manage_users boolean Optional

Can create/edit roles and invite/remove collaborators

attributes.can_manage_shared_filters boolean Optional

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

attributes.can_manage_upload_collections boolean Optional

Can create/edit upload collections

attributes.can_manage_build_triggers boolean Optional

Can create/edit Build triggers

attributes.can_manage_webhooks boolean Optional

Can create/edit webhooks

attributes.can_manage_environments boolean Optional

Can create/delete sandbox environments and promote them to primary environment

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/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.positive_item_type_permissions Optional

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

Type: Array<object>

environment string Required

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

Example:

"main"

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create Optional

duplicate Optional

delete Optional

publish Optional

edit_creator Optional

take_over Optional

move_to_stage Optional

item_type undefined Optional

workflow undefined Optional

on_stage null, string Optional

to_stage null, string Optional

on_creator enum, null Optional

Permitted creator

Example:

"self"

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, null Optional

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

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

attributes.negative_item_type_permissions Optional

Prohibited actions on a model (or all) for a role

Type: Array<object>

environment string Required

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

Example:

"main"

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create Optional

duplicate Optional

delete Optional

publish Optional

edit_creator Optional

take_over Optional

move_to_stage Optional

item_type undefined Optional

workflow undefined Optional

on_stage null, string Optional

to_stage null, string Optional

on_creator enum, null Optional

Permitted creator

Example:

"self"

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, null Optional

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

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

attributes.positive_upload_permissions Optional

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create 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, null Optional

Permitted creator

Example:

"self"

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, null Optional

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in specific locale (locale must be defined)

not_localized Optional

Non-localized content

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

attributes.negative_upload_permissions Optional

Prohibited actions on a model (or all) for a role

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create 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, null Optional

Permitted creator

Example:

"self"

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, null Optional

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in specific locale (locale must be defined)

not_localized Optional

Non-localized content

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

attributes.positive_build_trigger_permissions Optional

Allowed build triggers for a role

Type: Array<object>

build_trigger undefined Optional

attributes.negative_build_trigger_permissions Optional

Prohibited build triggers for a role

Type: Array<object>

build_trigger undefined Optional

meta.final_permissions object Optional

The final set of permissions considering also inherited roles

can_edit_site boolean Required

Can change project global properties

can_edit_favicon boolean Required

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

can_edit_schema boolean Required

Can create/edit models and plugins

can_manage_menu boolean Required

Can customize content navigation bar

can_manage_users boolean Required

Can create/edit roles and invite/remove collaborators

can_manage_environments boolean Required

Can create/delete sandbox environments and promote them to primary environment

can_manage_webhooks boolean Required

Can create/edit webhooks

environments_access enum Required

Specifies the environments the user can access

Example:

"primary_only"

all Optional

Can access all environments

primary_only Optional

Can access primary environment only

sandbox_only Optional

Can access sandbox environments only

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/edit workflows

can_edit_environment boolean Required

Can change locales, timezone and UI theme

can_promote_environments boolean Required

Can promote environments to primary and manage maintenance mode

can_manage_shared_filters boolean Required

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

can_manage_build_triggers boolean Required

Can create/edit Build triggers

can_manage_upload_collections boolean Required

Can create/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

positive_item_type_permissions Required

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

Type: Array<object>

environment string Required

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

Example:

"main"

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create Optional

duplicate Optional

delete Optional

publish Optional

edit_creator Optional

take_over Optional

move_to_stage Optional

item_type undefined Optional

workflow undefined Optional

on_stage null, string Optional

to_stage null, string Optional

on_creator enum, null Optional

Permitted creator

Example:

"self"

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, null Optional

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

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

negative_item_type_permissions Required

Prohibited actions on a model (or all) for a role

Type: Array<object>

environment string Required

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

Example:

"main"

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create Optional

duplicate Optional

delete Optional

publish Optional

edit_creator Optional

take_over Optional

move_to_stage Optional

item_type undefined Optional

workflow undefined Optional

on_stage null, string Optional

to_stage null, string Optional

on_creator enum, null Optional

Permitted creator

Example:

"self"

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, null Optional

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

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

positive_upload_permissions Required

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

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create 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, null Optional

Permitted creator

Example:

"self"

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, null Optional

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in specific locale (locale must be defined)

not_localized Optional

Non-localized content

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

negative_upload_permissions Required

Prohibited actions on a model (or all) for a role

Type: Array<object>

action enum Required

Permitted action

Example:

"all"

all Optional

read Optional

update Optional

create 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, null Optional

Permitted creator

Example:

"self"

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, null Optional

Permitted content scope

Example:

"all"

all Optional

Any content (localized/unlocalized)

localized Optional

Localized content in specific locale (locale must be defined)

not_localized Optional

Non-localized content

locale string, null Optional

Permitted localized content in this locale. Required when localization_scope is localized

Example:

"en"

positive_build_trigger_permissions Required

Allowed build triggers for a role

Type: Array<object>

build_trigger undefined Optional

negative_build_trigger_permissions Required

Prohibited build triggers for a role

Type: Array<object>

build_trigger undefined 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
PUT https://site-api.datocms.com/roles/:role_id 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
    "id": "34"
11
  }
12
}

1
curl -g 'https://site-api.datocms.com/roles/:role_id' \
2
  -X PUT \
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","id":"34"}}'

1
await fetch("https://site-api.datocms.com/roles/:role_id", {
2
  method: "PUT",
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({ data: { type: "role", id: "34" } }),
10
});

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_upload_collections": true,
20
      "can_manage_environments": true,
21
      "can_manage_webhooks": true,
22
      "environments_access": "primary_only",
23
      "can_manage_sso": true,
24
      "can_access_audit_log": true,
25
      "can_manage_workflows": true,
26
      "can_edit_environment": true,
27
      "can_promote_environments": true,
28
      "can_manage_build_triggers": true,
29
      "can_manage_access_tokens": true,
30
      "can_perform_site_search": true,
31
      "can_access_build_events_log": true,
32
      "positive_item_type_permissions": [
33
        {
34
          "environment": "main",
35
          "action": "all"
36
        }
37
      ],
38
      "negative_item_type_permissions": [
39
        {
40
          "environment": "main",
41
          "action": "all"
42
        }
43
      ],
44
      "positive_upload_permissions": [
45
        {
46
          "action": "all",
47
          "environment": "main"
48
        }
49
      ],
50
      "negative_upload_permissions": [
51
        {
52
          "action": "all",
53
          "environment": "main"
54
        }
55
      ],
56
      "positive_build_trigger_permissions": [
57
        {}
58
      ],
59
      "negative_build_trigger_permissions": [
60
        {}
61
      ]
62
    },
63
    "relationships": {
64
      "inherits_permissions_from": {
65
        "data": [
66
          {
67
            "type": "role",
68
            "id": "34"
69
          }
70
        ]
71
      }
72
    },
73
    "meta": {
74
      "final_permissions": {
75
        "can_edit_site": true,
76
        "can_edit_favicon": true,
77
        "can_edit_schema": true,
78
        "can_manage_menu": true,
79
        "can_manage_users": true,
80
        "can_manage_environments": true,
81
        "can_manage_webhooks": true,
82
        "environments_access": "primary_only",
83
        "can_manage_sso": true,
84
        "can_access_audit_log": true,
85
        "can_manage_workflows": true,
86
        "can_edit_environment": true,
87
        "can_promote_environments": true,
88
        "can_manage_shared_filters": true,
89
        "can_manage_build_triggers": true,
90
        "can_manage_upload_collections": true,
91
        "can_manage_access_tokens": true,
92
        "can_perform_site_search": true,
93
        "can_access_build_events_log": true,
94
        "positive_item_type_permissions": [
95
          {
96
            "environment": "main",
97
            "action": "all"
98
          }
99
        ],
100
        "negative_item_type_permissions": [
101
          {
102
            "environment": "main",
103
            "action": "all"
104
          }
105
        ],
106
        "positive_upload_permissions": [
107
          {
108
            "action": "all",
109
            "environment": "main"
110
          }
111
        ],
112
        "negative_upload_permissions": [
113
          {
114
            "action": "all",
115
            "environment": "main"
116
          }
117
        ],
118
        "positive_build_trigger_permissions": [
119
          {}
120
        ],
121
        "negative_build_trigger_permissions": [
122
          {}
123
        ]
124
      }
125
    }
126
  }
127
}

Did this doc help you?

Need help?

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