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.