Home
Content Management API
Main resources
Upload-related
Site Search
Environments
UI
Workflows
Async jobs
Roles & permissions
Webhooks
Hosting & CI integrations
Subscription
Enterprise
    Choose your language:
    Create a new role

    When creating roles you can pass a set of site-wide settings or 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',
      itemType: '44',
      onCreator: 'self'
    }
    Parameters
    name  string  Optional

    The name of the role

    canEditFavicon  boolean  Optional

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

    canEditSite  boolean  Optional

    Can change project name and 2FA settings

    canEditSchema  boolean  Optional

    Can create/edit models and plugins

    canManageMenu  boolean  Optional

    Can customize content navigation bar

    canEditEnvironment  boolean  Optional

    Can change locales, timezone and UI theme

    canPromoteEnvironments  boolean  Optional

    Can promote environments to primary and manage maintenance mode

    environmentsAccess  enum  Optional

    Specifies the environments the user can access

    canManageUsers  boolean  Optional

    Can create/edit roles and invite/remove collaborators

    canManageSharedFilters  boolean  Optional

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

    canManageBuildTriggers  boolean  Optional

    Can create/edit Build triggers

    canManageWebhooks  boolean  Optional

    Can create/edit webhooks

    canManageEnvironments  boolean  Optional

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

    canManageSso  boolean  Optional

    Can manage Single Sign-On settings

    canAccessAuditLog  boolean  Optional

    Can access Audit Log

    canManageWorkflows  boolean  Optional

    Can create/edit workflows

    canManageAccessTokens  boolean  Optional

    Can manage API tokens

    canPerformSiteSearch  boolean  Optional

    Can perform Site Search API calls

    canAccessBuildEventsLog  boolean  Optional

    Can access the build events log

    positiveItemTypePermissions  Array<object>  Optional

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

    negativeItemTypePermissions  Array<object>  Optional

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

    positiveUploadPermissions  Array<object>  Optional

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

    negativeUploadPermissions  Array<object>  Optional

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

    positiveBuildTriggerPermissions  Array<object>  Optional

    Allowed build triggers for a role

    negativeBuildTriggerPermissions  Array<object>  Optional

    Prohibited build triggers for a role

    meta.finalPermissions  object  Optional

    The final set of permissions considering also inherited roles

    inheritsPermissionsFrom  Array<role.id>  Optional

    The roles from which this role inherits permissions

    Returns
    Returns a role object.

    Examples

    Example code:
    const SiteClient = require('datocms-client').SiteClient;
    const client = new SiteClient('YOUR-API-TOKEN');
    client.role.create({
      name: 'Editor',
      canEditFavicon: true,
      canEditSite: true,
      canEditSchema: true,
      canManageMenu: true,
      canEditEnvironment: true,
      canPromoteEnvironments: true,
      environmentsAccess: 'primary_only',
      canManageUsers: true,
      canManageSharedFilters: true,
      canManageBuildTriggers: true,
      canManageWebhooks: true,
      canManageEnvironments: true,
      canManageSso: true,
      canAccessAuditLog: true,
      canManageWorkflows: true,
      canManageAccessTokens: true,
      canPerformSiteSearch: true,
      canAccessBuildEventsLog: true,
      positiveItemTypePermissions: [
        {
          itemType: '44',
          workflow: 'approval_by_editors',
          onStage: '',
          toStage: '',
          environment: 'main',
          action: 'all',
          onCreator: 'self',
          localizationScope: 'all',
          locale: 'en'
        }
      ],
      negativeItemTypePermissions: [
        {
          itemType: '44',
          workflow: 'approval_by_editors',
          onStage: '',
          toStage: '',
          environment: 'main',
          action: 'all',
          onCreator: 'self',
          localizationScope: 'all',
          locale: 'en'
        }
      ],
      positiveUploadPermissions: [
        {
          environment: 'main',
          action: 'all',
          onCreator: 'self',
          localizationScope: 'all',
          locale: 'en'
        }
      ],
      negativeUploadPermissions: [
        {
          environment: 'main',
          action: 'all',
          onCreator: 'self',
          localizationScope: 'all',
          locale: 'en'
        }
      ],
      positiveBuildTriggerPermissions: [
        {
          buildTrigger: '1822'
        }
      ],
      negativeBuildTriggerPermissions: [
        {
          buildTrigger: '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: 'approval_by_editors',
              on_stage: '',
              to_stage: '',
              environment: 'main',
              action: 'all',
              on_creator: 'self',
              localization_scope: 'all',
              locale: 'en'
            }
          ],
          negative_item_type_permissions: [
            {
              item_type: '44',
              workflow: 'approval_by_editors',
              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'
            }
          ]
        }
      },
      inheritsPermissionsFrom: [
        '34'
      ]
    })
    .then((role) => {
      console.log(role);
    })
    .catch((error) => {
      console.error(error);
    });
    Returned output:
    > node example.js
    {
      "id": "34",
      "name": "Editor",
      "canEditFavicon": true,
      "canEditSite": true,
      "canEditSchema": true,
      "canManageMenu": true,
      "canEditEnvironment": true,
      "canPromoteEnvironments": true,
      "environmentsAccess": "primary_only",
      "canManageUsers": true,
      "canManageSharedFilters": true,
      "canManageBuildTriggers": true,
      "canManageWebhooks": true,
      "canManageEnvironments": true,
      "canManageSso": true,
      "canAccessAuditLog": true,
      "canManageWorkflows": true,
      "canManageAccessTokens": true,
      "canPerformSiteSearch": true,
      "canAccessBuildEventsLog": true,
      "positiveItemTypePermissions": [
        {
          "itemType": "44",
          "workflow": "approval_by_editors",
          "onStage": "",
          "toStage": "",
          "environment": "main",
          "action": "all",
          "onCreator": "self",
          "localizationScope": "all",
          "locale": "en"
        }
      ],
      "negativeItemTypePermissions": [
        {
          "itemType": "44",
          "workflow": "approval_by_editors",
          "onStage": "",
          "toStage": "",
          "environment": "main",
          "action": "all",
          "onCreator": "self",
          "localizationScope": "all",
          "locale": "en"
        }
      ],
      "positiveUploadPermissions": [
        {
          "environment": "main",
          "action": "all",
          "onCreator": "self",
          "localizationScope": "all",
          "locale": "en"
        }
      ],
      "negativeUploadPermissions": [
        {
          "environment": "main",
          "action": "all",
          "onCreator": "self",
          "localizationScope": "all",
          "locale": "en"
        }
      ],
      "positiveBuildTriggerPermissions": [
        {
          "buildTrigger": "1822"
        }
      ],
      "negativeBuildTriggerPermissions": [
        {
          "buildTrigger": "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": "approval_by_editors",
              "on_stage": "",
              "to_stage": "",
              "environment": "main",
              "action": "all",
              "on_creator": "self",
              "localization_scope": "all",
              "locale": "en"
            }
          ],
          "negative_item_type_permissions": [
            {
              "item_type": "44",
              "workflow": "approval_by_editors",
              "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"
            }
          ]
        }
      },
      "inheritsPermissionsFrom": [
        "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.