Show examples in:

Endpoint info

Available examples

Content Management API > Role

Create a new role

When creating roles you can pass a number of project-wide permissions, plus more granular permissions on models and build triggers.

For models you can specify the action that can be done, on which models and on records created by who.

The actions that can be performed are:

all: everything
read: read-only
update: update records, to be used together with read if you want to be able to read and update
create: create new records
delete: delete records
publish: mark a record as published
edit_creator: change the creator of a record
take_over: when two people are working on the same record, you can take over the control of the record

Then you should specify the models on which the actions should be performed.

Finally you have the option to specify if you can perform the allowed actions on records created by:

anyone: meaning every record
self: only on records created by the user
role: only on records created by users with the same role

The resulting object should look something like this:

1
{
2
  action: 'all',
3
  item_type: { type: 'item_type', id: '44' },
4
  onCreator: 'self'
5
}

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 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 Required

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