Home
Content Management API
Main resources
Upload-related
Site Search
Environments
UI
Workflows
Async jobs
Roles & permissions
Webhooks
Hosting & CI integrations
Subscription
Enterprise
Show examples in:
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:

{
  action: 'all',
  item_type: { type: 'item_type', id: '44' },
  onCreator: 'self'
}

Body Parameters

name  Required  string  Example: "Editor"

The name of the role

can_edit_favicon  Optional  boolean  Example: true

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

can_edit_site  Optional  boolean  Example: true

Can change project global properties

can_edit_schema  Optional  boolean  Example: true

Can create/edit models and plugins

can_manage_menu  Optional  boolean  Example: true

Can customize content navigation bar

can_edit_environment  Optional  boolean  Example: true

Can change locales, timezone and UI theme

can_promote_environments  Optional  boolean  Example: true

Can promote environments to primary and manage maintenance mode

environments_access  Optional  enum  Example: "primary_only"

Specifies the environments the user can access

can_manage_users  Optional  boolean  Example: true

Can create/edit roles and invite/remove collaborators

can_manage_shared_filters  Optional  boolean  Example: true

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

can_manage_build_triggers  Optional  boolean  Example: true

Can create/edit Build triggers

can_manage_webhooks  Optional  boolean  Example: true

Can create/edit webhooks

can_manage_environments  Optional  boolean  Example: true

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

can_manage_sso  Optional  boolean  Example: true

Can manage Single Sign-On settings

can_access_audit_log  Optional  boolean  Example: true

Can access Audit Log

can_manage_workflows  Optional  boolean  Example: true

Can create/edit workflows

can_manage_access_tokens  Optional  boolean  Example: true

Can manage API tokens

can_perform_site_search  Optional  boolean  Example: true

Can perform Site Search API calls

can_access_build_events_log  Optional  boolean  Example: true

Can access the build events log

positive_item_type_permissions  Optional  Array<object>

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

negative_item_type_permissions  Optional  Array<object>

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

positive_upload_permissions  Optional  Array<object>

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

negative_upload_permissions  Optional  Array<object>

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

positive_build_trigger_permissions  Optional  Array<object>

Allowed build triggers for a role

negative_build_trigger_permissions  Optional  Array<object>

Prohibited build triggers for a role

meta.final_permissions  Optional  object

The final set of permissions considering also inherited roles

inherits_permissions_from  Optional  Array of { type: "role", id: role.id }

The roles from which this role inherits permissions

Returns

Returns a role resource object.

Examples

Example Basic example 
import { buildClient } from '@datocms/cma-client-node';
async function run() {
  const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
  
  const role = await client.roles.create({
    name: 'Editor'
  });
  
  console.log(role);
}
run();
Did this doc help you?
Still 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.