Sanity Studio v3 launches Dec 8th - See it in action at Sanity Product Day →

Roles

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.

Enterprise Feature

Custom roles and permissions are only available on Enterprise plans. The Team and Business plans include a set number of built-in roles to help control access for users across your organization.

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.

  • AdministratorAll plans

    Read and write access to all datasets, with full access to all project settings.

  • ViewerAll plans

    Read-only access to all datasets, with no access to project settings.

  • EditorAll plans

    Read and write access to all datasets, with limited access to project settings.

  • DeveloperTeam, Business, and Enterprise

    Read and write access to all datasets, with access to project settings for developers.

  • ContributorBusiness and Enterprise

    Read and write access to draft content within all datasets, with no access to project settings. Can write but not publish documents.

  • CustomEnterprise

    Fully custom roles and permissions, with custom access to project settings.

Assigning roles to members

To assign roles to your 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.

Each member may be assigned multiple roles. Permissions granted to the member are cumulative, meaning that each member will have access to your Content Lake equal to that of the most privileged role they are assigned.

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.

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.

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.

Gotcha

In order for a role to have access to the project, Project Details should be set to read. For content editor roles, also setting Project Members to read will ensure they get the best studio experience with the full advantage of Presence features.

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.

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.

Gotcha

If your dataset is public all project members will have read access to your published content even if their role is set to no access!

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.

Gotcha

The filter does not support dereferencing! This will not work: referenceField->! Instead, check against the _ref property when creating custom resources: referenceField._ref == "my-referenced-doc-id".

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.

Protip

GROQ is Sanity's open-source query language for JSON. Learn more about GROQ in the docs!

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

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.

Was this article helpful?