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  Required

    The name of the role

    canEditSite  boolean  Required

    Can change project name and 2FA settings

    canEditFavicon  boolean  Required

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

    canEditSchema  boolean  Required

    Can create/edit models, plugins and customize content navigation bar

    canManageUsers  boolean  Required

    Can create/edit roles and invite/remove collaborators

    canManageEnvironments  boolean  Required

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

    canManageWebhooks  boolean  Required

    Can create/edit webhooks

    environmentsAccess  enum  Required

    Specifies the environments the user can access

    canManageSso  boolean  Required

    Can manage Single Sign-On settings

    canEditEnvironment  boolean  Required

    Can change locales, timezone and UI theme

    canManageBuildTriggers  boolean  Required

    Can create/edit Build triggers

    canManageAccessTokens  boolean  Required

    Can manage API tokens

    canPerformSiteSearch  boolean  Required

    Can perform Site Search API calls

    positiveItemTypePermissions  array[object]  Required

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

    negativeItemTypePermissions  array[object]  Required

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

    positiveBuildTriggerPermissions  array[object]  Required

    Allowed build triggers for a role

    negativeBuildTriggerPermissions  array[object]  Required

    Prohibited build triggers for a role

    canManageSharedFilters  boolean  Optional

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

    Returns
    Returns a role object.

    Examples

    Example code:
    const SiteClient = require('datocms-client').SiteClient;
    const client = new SiteClient('YOUR-API-TOKEN');
    client.roles.create({
    name: 'Editor',
    canEditFavicon: true,
    canEditSite: true,
    canEditSchema: true,
    canEditEnvironment: true,
    environmentsAccess: 'primary_only',
    canManageUsers: true,
    canManageSharedFilters: true,
    canManageBuildTriggers: true,
    canManageWebhooks: true,
    canManageEnvironments: true,
    canManageSso: true,
    canManageAccessTokens: true,
    canPerformSiteSearch: true,
    positiveItemTypePermissions: [
    {
    itemType: '44',
    environment: 'master',
    action: 'all',
    onCreator: 'self'
    }
    ],
    negativeItemTypePermissions: [
    {
    itemType: '44',
    environment: 'master',
    action: 'all',
    onCreator: 'self'
    }
    ],
    positiveBuildTriggerPermissions: [
    {
    buildTrigger: '1822'
    }
    ],
    negativeBuildTriggerPermissions: [
    {
    buildTrigger: '1822'
    }
    ]
    })
    .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,
    "canEditEnvironment": true,
    "environmentsAccess": "primary_only",
    "canManageUsers": true,
    "canManageSharedFilters": true,
    "canManageBuildTriggers": true,
    "canManageWebhooks": true,
    "canManageEnvironments": true,
    "canManageSso": true,
    "canManageAccessTokens": true,
    "canPerformSiteSearch": true,
    "positiveItemTypePermissions": [
    {
    "itemType": "44",
    "environment": "master",
    "action": "all",
    "onCreator": "self"
    }
    ],
    "negativeItemTypePermissions": [
    {
    "itemType": "44",
    "environment": "master",
    "action": "all",
    "onCreator": "self"
    }
    ],
    "positiveBuildTriggerPermissions": [
    {
    "buildTrigger": "1822"
    }
    ],
    "negativeBuildTriggerPermissions": [
    {
    "buildTrigger": "1822"
    }
    ]
    }