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'
    }

    Parameters

    name  string  Required

    The name of the role

    can_edit_favicon  boolean  Optional

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

    can_edit_site  boolean  Optional

    Can change project name and 2FA settings

    can_edit_schema  boolean  Optional

    Can create/edit models and plugins

    can_manage_menu  boolean  Optional

    Can customize content navigation bar

    can_edit_environment  boolean  Optional

    Can change locales, timezone and UI theme

    can_promote_environments  boolean  Optional

    Can promote environments to primary and manage maintenance mode

    environments_access  enum  Optional

    Specifies the environments the user can access

    can_manage_users  boolean  Optional

    Can create/edit roles and invite/remove collaborators

    can_manage_shared_filters  boolean  Optional

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

    can_manage_build_triggers  boolean  Optional

    Can create/edit Build triggers

    can_manage_webhooks  boolean  Optional

    Can create/edit webhooks

    can_manage_environments  boolean  Optional

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

    can_manage_sso  boolean  Optional

    Can manage Single Sign-On settings

    can_access_audit_log  boolean  Optional

    Can access Audit Log

    can_manage_workflows  boolean  Optional

    Can create/edit workflows

    can_manage_access_tokens  boolean  Optional

    Can manage API tokens

    can_perform_site_search  boolean  Optional

    Can perform Site Search API calls

    can_access_build_events_log  boolean  Optional

    Can access the build events log

    positive_item_type_permissions  Array<object>  Optional

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

    negative_item_type_permissions  Array<object>  Optional

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

    positive_upload_permissions  Array<object>  Optional

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

    negative_upload_permissions  Array<object>  Optional

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

    positive_build_trigger_permissions  Array<object>  Optional

    Allowed build triggers for a role

    negative_build_trigger_permissions  Array<object>  Optional

    Prohibited build triggers for a role

    meta.final_permissions  object  Optional

    The final set of permissions considering also inherited roles

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

    The roles from which this role inherits permissions

    Returns

    Returns a role resource object.

    Examples

    Example code:
    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',
        can_edit_favicon: true,
        can_edit_site: true,
        can_edit_schema: true,
        can_manage_menu: true,
        can_edit_environment: true,
        can_promote_environments: true,
        environments_access: 'primary_only',
        can_manage_users: true,
        can_manage_shared_filters: true,
        can_manage_build_triggers: true,
        can_manage_webhooks: true,
        can_manage_environments: true,
        can_manage_sso: true,
        can_access_audit_log: true,
        can_manage_workflows: true,
        can_manage_access_tokens: true,
        can_perform_site_search: true,
        can_access_build_events_log: true,
        positive_item_type_permissions: [
          {
            item_type: '44',
            workflow: '439239',
            on_stage: '',
            to_stage: '',
            environment: 'main',
            action: 'all',
            on_creator: 'self',
            localization_scope: 'all',
            locale: 'en'
          }
        ],
        negative_item_type_permissions: [
          {
            item_type: '44',
            workflow: '439239',
            on_stage: '',
            to_stage: '',
            environment: 'main',
            action: 'all',
            on_creator: 'self',
            localization_scope: 'all',
            locale: 'en'
          }
        ],
        positive_upload_permissions: [
          {
            environment: 'main',
            action: 'all',
            on_creator: 'self',
            localization_scope: 'all',
            locale: 'en'
          }
        ],
        negative_upload_permissions: [
          {
            environment: 'main',
            action: 'all',
            on_creator: 'self',
            localization_scope: 'all',
            locale: 'en'
          }
        ],
        positive_build_trigger_permissions: [
          {
            build_trigger: '1822'
          }
        ],
        negative_build_trigger_permissions: [
          {
            build_trigger: '1822'
          }
        ],
        meta: {
          final_permissions: {
            can_edit_favicon: true,
            can_edit_site: true,
            can_edit_schema: true,
            can_manage_menu: true,
            can_edit_environment: true,
            can_promote_environments: true,
            environments_access: 'primary_only',
            can_manage_users: true,
            can_manage_shared_filters: true,
            can_manage_build_triggers: true,
            can_manage_webhooks: true,
            can_manage_environments: true,
            can_manage_sso: true,
            can_access_audit_log: true,
            can_manage_workflows: true,
            can_manage_access_tokens: true,
            can_perform_site_search: true,
            can_access_build_events_log: true,
            positive_item_type_permissions: [
              {
                item_type: '44',
                workflow: '439239',
                on_stage: '',
                to_stage: '',
                environment: 'main',
                action: 'all',
                on_creator: 'self',
                localization_scope: 'all',
                locale: 'en'
              }
            ],
            negative_item_type_permissions: [
              {
                item_type: '44',
                workflow: '439239',
                on_stage: '',
                to_stage: '',
                environment: 'main',
                action: 'all',
                on_creator: 'self',
                localization_scope: 'all',
                locale: 'en'
              }
            ],
            positive_upload_permissions: [
              {
                environment: 'main',
                action: 'all',
                on_creator: 'self',
                localization_scope: 'all',
                locale: 'en'
              }
            ],
            negative_upload_permissions: [
              {
                environment: 'main',
                action: 'all',
                on_creator: 'self',
                localization_scope: 'all',
                locale: 'en'
              }
            ],
            positive_build_trigger_permissions: [
              {
                build_trigger: '1822'
              }
            ],
            negative_build_trigger_permissions: [
              {
                build_trigger: '1822'
              }
            ]
          }
        },
        inherits_permissions_from: [
          {
            type: 'role',
            id: '34'
          }
        ]
      });
      
      console.log(role);
    }
    run();
    Returned output:
    {
      id: '34',
      name: 'Editor',
      can_edit_favicon: true,
      can_edit_site: true,
      can_edit_schema: true,
      can_manage_menu: true,
      can_edit_environment: true,
      can_promote_environments: true,
      environments_access: 'primary_only',
      can_manage_users: true,
      can_manage_shared_filters: true,
      can_manage_build_triggers: true,
      can_manage_webhooks: true,
      can_manage_environments: true,
      can_manage_sso: true,
      can_access_audit_log: true,
      can_manage_workflows: true,
      can_manage_access_tokens: true,
      can_perform_site_search: true,
      can_access_build_events_log: true,
      positive_item_type_permissions: [
        {
          item_type: '44',
          workflow: '439239',
          on_stage: '',
          to_stage: '',
          environment: 'main',
          action: 'all',
          on_creator: 'self',
          localization_scope: 'all',
          locale: 'en'
        }
      ],
      negative_item_type_permissions: [
        {
          item_type: '44',
          workflow: '439239',
          on_stage: '',
          to_stage: '',
          environment: 'main',
          action: 'all',
          on_creator: 'self',
          localization_scope: 'all',
          locale: 'en'
        }
      ],
      positive_upload_permissions: [
        {
          environment: 'main',
          action: 'all',
          on_creator: 'self',
          localization_scope: 'all',
          locale: 'en'
        }
      ],
      negative_upload_permissions: [
        {
          environment: 'main',
          action: 'all',
          on_creator: 'self',
          localization_scope: 'all',
          locale: 'en'
        }
      ],
      positive_build_trigger_permissions: [
        {
          build_trigger: '1822'
        }
      ],
      negative_build_trigger_permissions: [
        {
          build_trigger: '1822'
        }
      ],
      meta: {
        final_permissions: {
          can_edit_favicon: true,
          can_edit_site: true,
          can_edit_schema: true,
          can_manage_menu: true,
          can_edit_environment: true,
          can_promote_environments: true,
          environments_access: 'primary_only',
          can_manage_users: true,
          can_manage_shared_filters: true,
          can_manage_build_triggers: true,
          can_manage_webhooks: true,
          can_manage_environments: true,
          can_manage_sso: true,
          can_access_audit_log: true,
          can_manage_workflows: true,
          can_manage_access_tokens: true,
          can_perform_site_search: true,
          can_access_build_events_log: true,
          positive_item_type_permissions: [
            {
              item_type: '44',
              workflow: '439239',
              on_stage: '',
              to_stage: '',
              environment: 'main',
              action: 'all',
              on_creator: 'self',
              localization_scope: 'all',
              locale: 'en'
            }
          ],
          negative_item_type_permissions: [
            {
              item_type: '44',
              workflow: '439239',
              on_stage: '',
              to_stage: '',
              environment: 'main',
              action: 'all',
              on_creator: 'self',
              localization_scope: 'all',
              locale: 'en'
            }
          ],
          positive_upload_permissions: [
            {
              environment: 'main',
              action: 'all',
              on_creator: 'self',
              localization_scope: 'all',
              locale: 'en'
            }
          ],
          negative_upload_permissions: [
            {
              environment: 'main',
              action: 'all',
              on_creator: 'self',
              localization_scope: 'all',
              locale: 'en'
            }
          ],
          positive_build_trigger_permissions: [
            {
              build_trigger: '1822'
            }
          ],
          negative_build_trigger_permissions: [
            {
              build_trigger: '1822'
            }
          ]
        }
      },
      inherits_permissions_from: [
        {
          type: 'role',
          id: '34'
        }
      ]
    }
    Questions?
    We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.