Content Lake (Datastore)

Roles and permissions

API endpoints for managing roles and permissions

The Sanity Roles system is a granular way of attaching specific capabilities to specific groups of users. It is designed to function in a structured and flexible way. The goal of the Roles system is to provide a set of strong default permissions groups with an API for creating, managing, and using custom roles built the way your organization works with content.

Use the Access API

The preferred method for interacting with roles is the Access API. The project-based Roles API is still available, but the documentation below focuses on the Access API.

The Roles system is comprised primarily of:

  • Resources
  • Permissions
  • Roles
  • Members (users)

Resources

A resource defines an element of a Sanity project or organization on which a user can have special grants.

Permissions

Every resource has a list of permissions. These permissions represent actions that can be performed on the resource. A user or robot must be granted a permission (through a role) in order to perform the action.

The permission typically takes the form of {company}.{resourceType}.{objectName}.{action} but this is not always the case due to legacy terms.

There are both pre-defined and custom permissions. Pre-defined permissions are included with the product and are not editable.

Role

Roles define a set of grants which project members can have assigned to them. A project member can have many roles and grants, even within the same organization.

Default Roles

By default, there are specifically defined roles available for each plan type. Custom roles are available for Enterprise customers.

All plans

  • Administrator: Read and write access to all datasets, with full access to all project settings.
  • API Tokens
    • Editor Token (read+write)
    • Viewer Token (read-only)

Free

  • Administrator
  • Viewer: Can view all documents in all datasets within the project

Growth

  • Administrator
  • Editor
  • Viewer
  • Developer
  • Contributor: Read and write access to draft content within all datasets, with no access to project settings.

User

A user is a person that has one or more roles assigned to them.

A user is initially added to a resource via invitation or access request. A user that already has one role can be assigned roles in another project within the same organization or at the organization level without requiring a separate invite.

As an organization owns multiple resources, such as projects projects, any users with roles on these resources are also returned when reading the users of an organization.

If a user has roles in multiple projects, they are considered a single user and can be referenced by their sanityUserId. For example, inviting user A to project B and project C in the same organization will result in a single user with two memberships.

Token

A token is a unique string that can be used to authorize requests towards your content lake. A token can be given a role that defines its access to the system. Tokens should generally be considered secret.

Creating a custom role

This is a paid feature

This feature is available on certain Enterprise plans. Talk to sales to learn more.

To create a custom role, you need to create a new role, create any custom permissions for the role, attach those permissions to the role, and assign the role to individual users.

Create the role

A custom role is an object containing title, name, and description properties. In this example, a custom role with a name of custom-role, a title of My Custom Role, and a description of Custom role is created by sending that data to a project. This example adds the permission to deploy studios to the new role.

import { client } from "./client"; // use a configured @sanity/client

const { projectId } = client.config();
const response = await client.request({
  uri: `/access/project/${projectId}/roles`,
  method: 'POST',
  body: {
    name: 'custom-role',
    description: 'My custom role',
    title: 'Custom Role',
    permissions: [
      {
        name: 'sanity-project',
        action: 'deployStudio'
      }
    ]
  },
});

This is now a custom role with a single permission. You can update permissions add additional permissions to a role by appending the role name to the URI and using a PUT operation. See the Access API for details.

Inspecting available permissions

To see the available permission resources for the current project, you can send a GET request to the /permissions API endpoint for the current project.

Create a custom permission

This is a paid feature

This feature is available on certain Enterprise plans. Talk to sales to learn more.

The above examples create a new role using pre-made permission resources. When you need to create granular permissions for specific roles, you can create a custom permission resource.

To create a custom resource around a specific set of documents, you can use the sanity.document.filter schema. This schema provides a config option for adding a GROQ filter to specify a specific set of documents.

import { client } from "./client"; // use a configured @sanity/client

const { projectId } = client.config();
const response = await client.request({
  uri: `/access/project/${projectId}/permissions`,
  method: 'POST',
  body: {
    name: 'custom-permission',
    description: 'My custom permission',
    title: 'Custom Permission',
    type: 'sanity.document.filter',
    config: {
      filter: '_type == "post"'
    }
  }
});

This creates a new permission specific to documents with a _type of post. Custom document filter permissions automatically start with create, read, update, manage, manageHistory, and history actions.

Add custom permission to role

Using the earlier example, you can apply the custom permission to a role.

All permissions by default role

The following are the permissions for the default “Administrator” role available for various plans. You can view your default permission resources with the Access API.

Project administrator default permissions

Organization administrator default permissions

Previous

Common Sanity document types

Next

URL Format

Was this page helpful?