You're reading "Content Management API"

Role

A Role represents a specific set of actions an editor (or an API token) can perform on your administrative area.

The Role object

A Role object is returned as part of the response body of each successful Index, Show, Create, Update or Delete API call. The following table contains the list of all its fields along with their type, description and example values.

Object fields:
can_edit_faviconboolean

Can users edit the site favicon/global SEO settings?

This attribute is required
can_edit_schemaboolean

Can users edit the schema?

This attribute is required
can_edit_siteboolean

Can users edit the site settings?

This attribute is required
can_manage_access_tokensboolean

Can manage access tokens

This attribute is required
can_manage_deployment_environmentsboolean

Can users manage deployment environments?

This attribute is required
can_manage_shared_filtersboolean

Can users manage shared filters?

This attribute is required
can_manage_usersboolean

Can users invite other users?

This attribute is required
can_manage_webhooksboolean

Can users manage webhooks?

This attribute is required
can_perform_site_searchboolean

Can perform site search

This attribute is required
namestring

The name of the role

This attribute is required
negative_deployment_environment_permissionsarray
negative_item_type_permissionsarray
positive_deployment_environment_permissionsarray
positive_item_type_permissionsarray

List all roles

To list all roles, send a GET request to the /roles endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
GET https://site-api.datocms.com/roles HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": [ { "type": "role", "id": "34", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] }, "relationships": { "deployment_environments": { "data": [ { "type": "deployment_environment", "id": "1822" } ] }, "parent": { "data": null }, "children": { "data": [ { "type": "menu_item", "id": "34" } ] } } } ] }

Retrieve a role

To retrieve a role, send a GET request to the /roles/:role_id endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
GET https://site-api.datocms.com/roles/:role_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "role", "id": "34", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] }, "relationships": { "deployment_environments": { "data": [ { "type": "deployment_environment", "id": "1822" } ] }, "parent": { "data": null }, "children": { "data": [ { "type": "menu_item", "id": "34" } ] } } } }

Create a new role

To create a new role, send a POST request to the /roles endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
POST https://site-api.datocms.com/roles HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Content-Typeapplication/json
{ "data": { "type": "role", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] } } }
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "role", "id": "34", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] }, "relationships": { "deployment_environments": { "data": [ { "type": "deployment_environment", "id": "1822" } ] }, "parent": { "data": null }, "children": { "data": [ { "type": "menu_item", "id": "34" } ] } } } }

Update a role

To update a role, send a PUT request to the /roles/:role_id endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
PUT https://site-api.datocms.com/roles/:role_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Content-Typeapplication/json
{ "data": { "type": "role", "id": "34", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] } } }
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "role", "id": "34", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] }, "relationships": { "deployment_environments": { "data": [ { "type": "deployment_environment", "id": "1822" } ] }, "parent": { "data": null }, "children": { "data": [ { "type": "menu_item", "id": "34" } ] } } } }

Delete a role

To delete a role, send a DELETE request to the /roles/:role_id endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
DELETE https://site-api.datocms.com/roles/:role_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "role", "id": "34", "attributes": { "name": "Editor", "can_edit_favicon": true, "can_edit_site": true, "can_edit_schema": true, "can_manage_users": true, "can_manage_shared_filters": true, "can_manage_deployment_environments": true, "can_manage_webhooks": true, "can_manage_access_tokens": true, "can_perform_site_search": true, "positive_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "negative_item_type_permissions": [ { "item_type": "44", "action": "all", "on_creator": "self" } ], "positive_deployment_environment_permissions": [ { "deployment_environment": "1822" } ], "negative_deployment_environment_permissions": [ { "deployment_environment": "1822" } ] }, "relationships": { "deployment_environments": { "data": [ { "type": "deployment_environment", "id": "1822" } ] }, "parent": { "data": null }, "children": { "data": [ { "type": "menu_item", "id": "34" } ] } } } }