Roles

Sanity enforces user access control with roles. Roles help control resource access to datasets and documents.

You can manage access to content and settings in your Sanity Content Lake by setting roles and permissions for project members. Each member may have different roles for granular access control to your Content Lake. All projects have default roles available, but you can also create custom roles that define granular access to datasets and project settings. You can also use GROQ to define custom content resources. Content permissions are typically set to either all or individual datasets, but you can use Tags to group datasets that should share permissions.

Roles and permissions can be configured through the API, or through the project settings available at sanity.io/manage. This article will focus mainly on the latter option.

Each plan type has access to specifically defined roles. Custom roles are available for Enterprise customers.

To assign roles to users, navigate to the Member section in your project settings at sanity.io/manage. You'll see each project member's roles listed by their name and login info.

When using Single Sign-On (SSO), roles can be automatically assigned to users using rules that evaluate each user’s group membership in your identity provider. Role assignment can be restricted to be set only through mapping rules, or allow for manual modification. If role assignment is restricted to be set only through mapping rules, you cannot manually change the role of a user in this screen.

To define custom roles, navigate to the Access tab in your project settings. You will see a list of your currently defined roles with a summary of each role's access privileges. To create a new custom role, click the button in the upper right corner.

You will be asked to provide some basic details for your role.

Once created you'll have the option of adding members to the role or proceeding to define permissions and restrictions. These are divided into two main categories: Content Permissions and Management Permissions.

Users with the "Viewer" role are free and don't count toward a plan's available seats. If a user with the viewer role is assigned an additional role, that user will count as a billable user.

These settings grant a role access to your project's settings which are typically accessed in the project management console at sanity.io/manage. Access to a project's details and usage statistics, members and roles, API settings, and datasets and tags are currently available for configuration.

This is where you define the role's access to your Content Lake. You can grant any role wide-reaching privileges that extend to all your datasets or use GROQ filters to set up granular access to only certain content types.

Once you've navigated to the role you want to configure you'll be presented with a list of your datasets that can be individually configured, as well as the opportunity to set some base permissions for all datasets.

By default, all permissions are set to No access. Permissions cascade down from more general contexts to more specific ones, so it's generally better to start restrictive and grant privileges on each dataset separately as any permission granted on All datasets will override more restrictive settings in the individual datasets.

This hereditary characteristic of permissions is visualized when you go to edit the permission for a single dataset. The dialog shown below demonstrates how the final permissions for the dataset are derived from both the privileges set generally for all datasets and from the privileges set specifically for this dataset.

The base set of content resources available for access control are general in nature but powerful enough to cover many use-cases. You may grant privileges to read, create and update, and publish each of the widely encompassing options; All documents, Image assets, and File assets.

In addition to the basic set of permission scopes that lets you configure access to All documents, Image assets, and File assets, you may also create custom content resources to control access to particular content types, which you may then control the access to with your custom roles. To create a new content resource, find the Resources section in the left column menu, under the Access tab.

In our example, we'll be working with the default starter template called Movie Project. This gives us a prefilled dataset with content types like movie, person, and screening. Click the button in the top right of the section to create a new content resource.

Content resources leverage the power of GROQ to filter which content types are affected by the privileges you choose to grant. In this example, we're using a simple but powerful GROQ expression to return only documents of type movie.

Once you hit save, you should see your new content resource added to the list.

Revisiting the Roles section in the left column menu, we can now set movie-specific privileges on our custom role.

To test your role, make sure you have actually set the role on a member account and then proceed to log into the studio with the account in question.

Your account should be able to view, create, update and publish any document of the movie type, but should be unable to edit documents of any other type.

Tags are a useful feature that lets you group datasets with similar characteristics together so that roles and permissions can be conveniently set on multiple datasets in a single operation. You might create tags for different environments, such as production and staging, or combine tags for different publications and locales, E.g. elle us or vogue jp.

To create a new tag, navigate to the Datasets tab in your project settings and find the Tags section in the left column menu.

In the example shown below we'll be creating a tag for staging and production datasets for our movie blog, and then assigning editing privileges in both for our movie-critic role.

Once created, we can add datasets to the tag and define permissions to content resources for our custom roles.

The change is reflected and can be edited in the content permissions for the custom role.