Access Control

Sanity offers organization and project administrators to specify granular access controls to content. Users can be assigned a Role, which defines a set of grants for content edited within the Sanity studio. Depending on your plan, you can also onboard users via built-in SSO capabilities. Below are guides to both access features, along with a full API reference for specifying grants to content based on our GROQ query language.

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.

Default roles per plan

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

Administrator (All plans): Read and write access to all datasets, with full access to all project settings.

Viewer (All plans): Read-only access to all datasets, with no access to project settings.

Editor (Growth and Enterprise): Read and write access to all datasets, with limited access to project settings.Editors can modify existing datasets, but cannot create new ones.

Developer (Growth and Enterprise): Read and write access to all datasets, with access to project settings for developers.

Contributor (Growth and Enterprise): Read and write access to draft content within all datasets, with no access to project settings. Can write but not publish documents.

Custom (Enterprise): Fully custom roles and permissions, with custom access to project settings.

Assigning roles to members

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.

Add Project Members

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.

Member Roles

Creating custom roles

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.

Creating Custom Roles

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

Create new 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.

Management Permissions

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.

Content permissions

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.

Content permission

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.

Dataset Permissions

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.

Summary Permission

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.

Content resources

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.

Content Resources

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.

Configure 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.

All Resources

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

Role Privileges

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.

Testing Role

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.

Test Role Permissions

Insufficient Permission

Tags

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.