Roles API reference

Reference documentation for the Roles HTTP endpoints.

Use the Roles API to assign roles, grants, and permissions.

We suggest using the newer Access API for role management instead of this legacy Roles API.

Authentication

  • All requests must be authenticated.
  • Most endpoints require a specific permission, such as sanity.project.roles or sanity.project.members. The built-in Administrator role for a project or organization has every permission its endpoints need.

Base API server URL

Sanity API base URL

https://api.sanity.io/{apiVersion}

Variables

  • apiVersionstringdefault: "v2021-10-04"

    API version. These endpoints require v2021-06-07 or later.

Project

Endpoints for managing project-level roles and permissions

List users with roles

get/projects/{projectId}/acl

List the users and robots in a project and their roles. Requires the read permission on sanity.project.members.

Without the roles parameter, the list includes members who have no roles. With it, the list only includes members who have at least one of the given roles.

Path parameters

Query parameters

  • roles[]array

    Only return users who have at least one of these roles. Use the roles[] form, for example ?roles[]=editor or ?roles[]=editor&roles[]=viewer.

    A single plain ?roles=editor returns 400 with the message roles must be an array. Duplicate role names also return 400.

    items
    • itemsstring

Responses

200

List of users and their roles

    items
    • projectUserIdstring

      The project user ID

      Example:p.....
    • rolesarray
      Example
      [{"name":"administrator","title":"Administrator"}]
      Show child attributes
      items
      • namestring

        The role name

        Example:administrator
      • titlestring

        The role title

        Example:Administrator
    • isRobotboolean

      Whether the user is a robot

      Example:false
Examplesapplication/json
[
  {
    "projectUserId": "p.....",
    "roles": [
      {
        "name": "administrator",
        "title": "Administrator"
      }
    ],
    "isRobot": false
  }
]

Get a user's roles

get/projects/{projectId}/acl/{projectUserId}

Get the roles of a specific user in a project. Requires the read permission on sanity.project.members.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • projectUserIdstringrequired

    The project user ID, which starts with p. A Sanity user ID, which starts with g, returns 400.

Responses

200

User role information

  • projectUserIdstring

    The project user ID

    Example:p.....
  • rolesarray
    Example
    [{"name":"administrator","title":"Administrator"}]
    Show child attributes
    items
    • namestring

      The role name

      Example:administrator
    • titlestring

      The role title

      Example:Administrator
  • isRobotboolean

    Whether the user is a robot

    Example:false
Examplesapplication/json
{
  "projectUserId": "p.....",
  "roles": [
    {
      "name": "administrator",
      "title": "Administrator"
    }
  ],
  "isRobot": false
}

Add a role to a user

put/projects/{projectId}/acl/{projectUserId}

Add one or more roles to a user in a project. Send roleName for one role, or roleNames for several. Requires the update permission on sanity.project.members.

Set deleteExistingRoles to true to also remove the user's other roles in the project. When you do, the request fails if it would leave the project without an administrator.

A role can only be given to robots if its appliesToRobots is true, and to users if its appliesToUsers is true. Only a project administrator can add or remove the administrator role.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • projectUserIdstringrequired

    The project user ID, which starts with p

Request body application/json

Examplesapplication/json
{
  "roleName": "editor"
}

Responses

201

Roles updated. The response has no body. It also returns 201 when the user already had the roles.

Delete a role from a user

delete/projects/{projectId}/acl/{projectUserId}

Remove a role from a user in a project. Send roleName to remove one role. Omit roleName to remove all of the user's roles, which removes the user from the project and ends their project sessions. Requires the update permission on sanity.project.members.

A project must keep at least one administrator. Only a project administrator can remove the administrator role.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • projectUserIdstringrequired

    The project user ID, which starts with p

Request body application/json

  • roleNamestring

    The name of the role to remove. Omit it to remove all of the user's roles.

    Example:editor
Examplesapplication/json
{
  "roleName": "editor"
}

Responses

200

Role removed successfully

  • object
Examplesapplication/json
{}

List grants for the current user

get/projects/{projectId}/grants

List the project-level grants for the current user in a project. The user must be a member of the project.

Path parameters

Responses

200

The current user's project-level grants, grouped by permission resource type

  • object

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Examplesapplication/json
{
  "sanity.project": [
    {
      "id": "res-2kd9w0vc",
      "name": "sanity-project",
      "title": "Project",
      "description": null,
      "isCustom": false,
      "config": {},
      "grants": [
        {
          "name": "createSession",
          "params": {}
        },
        {
          "name": "delete",
          "params": {}
        },
        {
          "name": "deployStudio",
          "params": {}
        },
        {
          "name": "read",
          "params": {}
        },
        {
          "name": "update",
          "params": {}
        }
      ]
    }
  ]
}

Create a grant

post/projects/{projectId}/grants

Add one or more grants to a custom role in a project. A grant gives the role a permission on a permission resource. Identify the resource with permissionResourceId or permissionResourceName. Users get the grant when they're assigned the role. Requires the update permission on sanity.project.roles.

You can only add grants to custom roles. Requests for a built-in role return 400 with the message Can not modify grants on a non-custom role.

To add several grants to the same role, send roleName and a grants array instead. The grants are added together: if one fails, none are added.

Path parameters

Request body application/json

Examplesapplication/json
{
  "roleName": "translator",
  "permissionName": "read",
  "permissionResourceName": "articles"
}

Responses

200

No grants were created, or at least one grant's parameters were updated. Returns the grant configuration, or an array of configurations when you send grants.

  • roleNamestring

    The name of the role

    Example:translator
  • permissionNamestring

    The name of the permission

    Example:read
  • permissionResourceTypestring

    The name of the permission resource schema

    Example:sanity.document.filter
  • permissionResourceIdstring

    The ID of the permission resource

    Example:res-k2d8fj3a
  • paramsobject

    The permission parameters

    Example
    {}
  • tagIdstring|null

    Only returned when you remove a project grant. The ID of the tag the grant applied to, if any.

  • datasetIdstring|null

    Only returned when you remove a project grant. The ID of the dataset the grant applied to, if any.

Remove a grant

delete/projects/{projectId}/grants

Remove one or more grants from a custom role in a project. The request body has the same shape as when you create a grant. You can only remove grants from custom roles. Requires the update permission on sanity.project.roles.

A grant only matches if params is exactly the same as when the grant was created. If nothing matches, the request still returns 200.

Path parameters

Request body application/json

Examplesapplication/json
{
  "roleName": "translator",
  "permissionName": "read",
  "permissionResourceName": "articles"
}

Responses

200

Request processed. Returns the grant configuration, or an array of configurations when you send grants, whether or not a matching grant existed.

  • roleNamestring

    The name of the role

    Example:translator
  • permissionNamestring

    The name of the permission

    Example:read
  • permissionResourceTypestring

    The name of the permission resource schema

    Example:sanity.document.filter
  • permissionResourceIdstring

    The ID of the permission resource

    Example:res-k2d8fj3a
  • paramsobject

    The permission parameters

    Example
    {}
  • tagIdstring|null

    Only returned when you remove a project grant. The ID of the tag the grant applied to, if any.

  • datasetIdstring|null

    Only returned when you remove a project grant. The ID of the dataset the grant applied to, if any.

List grants for a project member

get/projects/{projectId}/grants/{projectUserId}

List the project-level grants for a specific member of a project. Requires the read permission on sanity.project.members.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • projectUserIdstringrequired

    The project user ID of the member, which starts with p

Responses

200

The member's grants, grouped by permission resource type

  • object

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

List all roles

get/projects/{projectId}/roles

List all roles in a project, including built-in roles, ordered by name. Requires the read permission on sanity.project.roles.

A built-in role can appear twice with the same name: once for users and once for robots. Check appliesToUsers and appliesToRobots to tell them apart.

Path parameters

Responses

200

List of roles

    items
    • namestring

      The role name

      Example:administrator
    • titlestring

      The role title

      Example:Administrator
    • descriptionstring

      A description of the role's permissions. An empty string if the role has no description.

      Example:Read and write access to all datasets, with full access to all project settings.
    • isCustomboolean

      Whether this is a custom role

      Example:false
    • projectIdstring

      The ID of the project this role belongs to

      Example:3do82whm
    • appliesToUsersboolean

      Whether the role can be given to users

      Example:true
    • appliesToRobotsboolean

      Whether the role can be given to robots

      Example:false
    • grantsobject

      Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Examplesapplication/json
[
  {
    "name": "translator",
    "title": "Translator",
    "description": "Edit translated documents",
    "isCustom": true,
    "projectId": "3do82whm",
    "appliesToUsers": true,
    "appliesToRobots": false,
    "grants": {
      "sanity.document.filter": [
        {
          "id": "res-k2d8fj3a",
          "name": "articles",
          "title": "Articles",
          "description": "Documents of type article",
          "isCustom": true,
          "config": {
            "filter": "_type == \"article\""
          },
          "grants": [
            {
              "name": "read",
              "params": {}
            },
            {
              "name": "update",
              "params": {}
            }
          ]
        }
      ]
    }
  }
]

Create a role

post/projects/{projectId}/roles

Create a custom role in a project. Requires the create permission on sanity.project.roles, and the project must have the advancedRolesManagement feature.

Path parameters

Request body application/json

  • namestringrequired

    The role name. Use lowercase letters, numbers, hyphens, and underscores. You can't use the name of a built-in role, or read, write, public, or custom.

    Example:translator
  • titlestringrequired

    The role title

    Example:Translator
  • descriptionstringdefault: ""

    A description of the role's permissions

    Example:Edit translated documents
  • appliesToUsersbooleandefault: true

    Whether the role applies to users

    Example:true
  • appliesToRobotsbooleandefault: true

    Whether the role applies to robots

    Example:false
Examplesapplication/json
{
  "name": "translator",
  "title": "Translator",
  "description": "Edit translated documents",
  "appliesToUsers": true,
  "appliesToRobots": false
}

Responses

201

Role created successfully

  • namestring

    The role name

    Example:administrator
  • titlestring

    The role title

    Example:Administrator
  • descriptionstring

    A description of the role's permissions. An empty string if the role has no description.

    Example:Read and write access to all datasets, with full access to all project settings.
  • isCustomboolean

    Whether this is a custom role

    Example:false
  • projectIdstring

    The ID of the project this role belongs to

    Example:3do82whm
  • appliesToUsersboolean

    Whether the role can be given to users

    Example:true
  • appliesToRobotsboolean

    Whether the role can be given to robots

    Example:false
  • grantsobject

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Examplesapplication/json
{
  "name": "translator",
  "title": "Translator",
  "description": "Edit translated documents",
  "isCustom": true,
  "projectId": "3do82whm",
  "appliesToUsers": true,
  "appliesToRobots": false,
  "grants": {}
}

List permission resource schemas

get/projects/{projectId}/permissionResourceSchemas

List the permission resource schemas available to projects, such as sanity.project.members, sanity.document.filter, and sanity.document.filter.mode. Each schema defines a type of permission resource and the permissions you can grant on it. Requires the read permission on sanity.project.roles.

To list the permission resources in a project, use GET /projects/{projectId}/permissionResources.

Path parameters

Responses

200

List of permission resource schemas. The example shows one entry; the response contains every project schema.

    items
    • idstring

      The ID of the permission resource schema

      Example:srp-2ve36erw
    • titlestring

      The title of the permission resource schema

      Example:Sanity Document Filter
    • descriptionstring

      The description of the permission resource schema

      Example:Defines a permission resource for a filtered collection of Sanity documents
    • namestring

      The name of the permission resource schema

      Example:sanity.document.filter
    • configarray
      Show child attributes
      items
      • namestring

        The name of the config parameter

        Example:filter
      • typestring

        The type of the config parameter

        Example:string
      • titlestring

        The title of the config parameter

        Example:Filter
      • descriptionstring

        The description of the config parameter

        Example:GROQ filter limiting the document collection
    • permissionsarray
      Show child attributes
      items
      • namestring

        The name of the permission

        Example:read
      • titlestring

        The title of the permission

        Example:Read
      • descriptionstring

        The description of the permission

        Example:Read documents matching the filter
      • paramsarray
        Show child attributes
        items
        • namestring

          The name of the parameter

          Example:tagName
        • typestring

          The type of the parameter

          Example:string
        • titlestring

          The title of the parameter

          Example:Tag Name
        • descriptionstring

          The description of the parameter

          Example:A tag to scope the permission
        • requiredboolean

          Whether the parameter is required. Only present on required parameters.

        • defaultValue

          The default value of the parameter, if it has one

          Example:false
Examplesapplication/json
[
  {
    "id": "srp-2ve36erw",
    "title": "Sanity Document Filter",
    "description": "Defines a permission resource for a filtered collection of Sanity documents",
    "name": "sanity.document.filter",
    "config": [
      {
        "name": "filter",
        "type": "string",
        "title": "Filter",
        "description": "GROQ filter limiting the document collection"
      }
    ],
    "permissions": [
      {
        "name": "read",
        "title": "Read",
        "description": "Read documents matching the filter",
        "params": [
          {
            "name": "tagName",
            "type": "string",
            "title": "Tag Name",
            "description": "A tag to scope the permission"
          },
          {
            "name": "dataset",
            "type": "string",
            "title": "Dataset Name",
            "description": "A dataset to scope the permission"
          }
        ]
      },
      {
        "name": "create",
        "title": "Create",
        "description": "Create documents matching the filter",
        "params": [
          {
            "name": "tagName",
            "type": "string",
            "title": "Tag Name",
            "description": "A tag to scope the permission"
          },
          {
            "name": "dataset",
            "type": "string",
            "title": "Dataset Name",
            "description": "A dataset to scope the permission"
          }
        ]
      }
    ]
  }
]

List permission resources

get/projects/{projectId}/permissionResources

List the permission resources in a project, both built-in and custom, ordered by ID. Requires the read permission on sanity.project.roles or sanity.organization.projects.

Path parameters

Responses

200

List of permission resources

    items
    • idstring

      The ID of the permission resource

      Example:res-k2d8fj3a
    • namestring

      The name of the permission resource

      Example:articles
    • titlestring

      The title of the permission resource

      Example:Articles
    • descriptionstring

      A description of the permission resource

      Example:Documents of type article
    • configobject

      The resource configuration. For sanity.document.filter resources, filter is a GROQ filter.

      Example
      {"filter":"_type == \"article\""}
    • isCustomboolean

      Whether the resource was created by a user rather than by Sanity

      Example:true
    • permissionResourceTypestring

      The name of the permission resource schema the resource is based on

      Example:sanity.document.filter

Create a permission resource

post/projects/{projectId}/permissionResources

Create a custom permission resource in a project. Set permissionResourceType to the name of a permission resource schema, and set config to match that schema's configuration. For sanity.document.filter, config.filter is a GROQ filter. The filter can't be empty, and can't contain a full query (*) or a dereference (->).

If you omit name, you can only refer to the resource by its ID.

Requires the update permission on sanity.project.roles, and the project must have the advancedRolesManagement feature.

Path parameters

Request body application/json

  • permissionResourceTypestringrequired

    The name of the permission resource schema to base the resource on

    Example:sanity.document.filter
  • namestring

    A unique name for the resource. Use lowercase letters, numbers, hyphens, and underscores. Can't start with res- or sanity.

    Example:articles
  • titlestringrequired

    The title of the resource

    Example:Articles
  • descriptionstring

    A description of the resource

    Example:Documents of type article
  • configobjectrequired

    Configuration that matches the permission resource schema's config. Unknown keys return 422.

    Example
    {"filter":"_type == \"article\""}
Examplesapplication/json
{
  "permissionResourceType": "sanity.document.filter",
  "name": "articles",
  "title": "Articles",
  "description": "Documents of type article",
  "config": {
    "filter": "_type == \"article\""
  }
}

Responses

201

Permission resource created

  • idstring

    The ID of the permission resource

    Example:res-k2d8fj3a
  • namestring

    The name of the permission resource

    Example:articles
  • titlestring

    The title of the permission resource

    Example:Articles
  • descriptionstring

    A description of the permission resource

    Example:Documents of type article
  • configobject

    The resource configuration. For sanity.document.filter resources, filter is a GROQ filter.

    Example
    {"filter":"_type == \"article\""}
  • isCustomboolean

    Whether the resource was created by a user rather than by Sanity

    Example:true
  • permissionResourceTypestring

    The name of the permission resource schema the resource is based on

    Example:sanity.document.filter
Examplesapplication/json
{
  "id": "res-k2d8fj3a",
  "name": "articles",
  "title": "Articles",
  "description": "Documents of type article",
  "config": {
    "filter": "_type == \"article\""
  },
  "isCustom": true,
  "permissionResourceType": "sanity.document.filter"
}

Get a permission resource

get/projects/{projectId}/permissionResources/{resourceId}

Get a permission resource in a project. Requires the read permission on sanity.project.roles or sanity.organization.projects.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • resourceIdstringrequired

    The ID or name of the permission resource. Values that start with res- are treated as IDs.

Responses

200

Permission resource

  • idstring

    The ID of the permission resource

    Example:res-k2d8fj3a
  • namestring

    The name of the permission resource

    Example:articles
  • titlestring

    The title of the permission resource

    Example:Articles
  • descriptionstring

    A description of the permission resource

    Example:Documents of type article
  • configobject

    The resource configuration. For sanity.document.filter resources, filter is a GROQ filter.

    Example
    {"filter":"_type == \"article\""}
  • isCustomboolean

    Whether the resource was created by a user rather than by Sanity

    Example:true
  • permissionResourceTypestring

    The name of the permission resource schema the resource is based on

    Example:sanity.document.filter
Examplesapplication/json
{
  "id": "res-k2d8fj3a",
  "name": "articles",
  "title": "Articles",
  "description": "Documents of type article",
  "config": {
    "filter": "_type == \"article\""
  },
  "isCustom": true,
  "permissionResourceType": "sanity.document.filter"
}

Update a permission resource

put/projects/{projectId}/permissionResources/{resourceId}

Update the title, description, or configuration of a permission resource. Sending config replaces the whole configuration. You can't change name or permissionResourceType.

This endpoint also updates built-in resources.

Requires the update permission on sanity.project.roles, and the project must have the advancedRolesManagement feature.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • resourceIdstringrequired

    The ID or name of the permission resource

Request body application/json

  • titlestring

    The title of the resource

  • descriptionstring

    A description of the resource

  • configobject

    Configuration that matches the permission resource schema's config. Replaces the existing configuration.

Examplesapplication/json
{
  "config": {
    "filter": "_type == \"article\""
  }
}

Responses

200

Permission resource updated

  • idstring

    The ID of the permission resource

    Example:res-k2d8fj3a
  • namestring

    The name of the permission resource

    Example:articles
  • titlestring

    The title of the permission resource

    Example:Articles
  • descriptionstring

    A description of the permission resource

    Example:Documents of type article
  • configobject

    The resource configuration. For sanity.document.filter resources, filter is a GROQ filter.

    Example
    {"filter":"_type == \"article\""}
  • isCustomboolean

    Whether the resource was created by a user rather than by Sanity

    Example:true
  • permissionResourceTypestring

    The name of the permission resource schema the resource is based on

    Example:sanity.document.filter
Examplesapplication/json
{
  "id": "res-k2d8fj3a",
  "name": "articles",
  "title": "Articles",
  "description": "Documents of type article",
  "config": {
    "filter": "_type == \"article\""
  },
  "isCustom": true,
  "permissionResourceType": "sanity.document.filter"
}

Delete a permission resource

delete/projects/{projectId}/permissionResources/{resourceId}

Delete a permission resource, and remove every grant that uses it. This endpoint also deletes built-in resources, which removes the matching grants from built-in roles.

Requires the update permission on sanity.project.roles, and the project must have the advancedRolesManagement feature.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • resourceIdstringrequired

    The ID or name of the permission resource

Responses

200

Permission resource deleted. The response has no body.

Delete a role

delete/projects/{projectId}/roles/{roleName}

Delete a custom role in a project. You can't delete built-in roles, or roles that are assigned to users or robots. Requires the delete permission on sanity.project.roles, and the project must have the advancedRolesManagement feature.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • roleNamestringrequired

    The name of the role

Responses

200

Role deleted successfully

  • object
Examplesapplication/json
{}

Get a role

get/projects/{projectId}/roles/{roleName}

Get a role in a project. Requires the read permission on sanity.project.roles.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • roleNamestringrequired

    The name of the role

Responses

200

OK

  • namestring

    The role name

    Example:administrator
  • titlestring

    The role title

    Example:Administrator
  • descriptionstring

    A description of the role's permissions. An empty string if the role has no description.

    Example:Read and write access to all datasets, with full access to all project settings.
  • isCustomboolean

    Whether this is a custom role

    Example:false
  • projectIdstring

    The ID of the project this role belongs to

    Example:3do82whm
  • appliesToUsersboolean

    Whether the role can be given to users

    Example:true
  • appliesToRobotsboolean

    Whether the role can be given to robots

    Example:false
  • grantsobject

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Examplesapplication/json
{
  "name": "translator",
  "title": "Translator",
  "description": "Edit translated documents",
  "isCustom": true,
  "projectId": "3do82whm",
  "appliesToUsers": true,
  "appliesToRobots": false,
  "grants": {
    "sanity.document.filter": [
      {
        "id": "res-k2d8fj3a",
        "name": "articles",
        "title": "Articles",
        "description": "Documents of type article",
        "isCustom": true,
        "config": {
          "filter": "_type == \"article\""
        },
        "grants": [
          {
            "name": "read",
            "params": {}
          },
          {
            "name": "update",
            "params": {}
          }
        ]
      }
    ]
  }
}

Update a role

put/projects/{projectId}/roles/{roleName}

Update a custom role in a project. Send only the fields you want to change. You can't rename a role, and you can't update built-in roles.

Requires the create permission on sanity.project.roles, and the project must have the advancedRolesManagement feature.

Path parameters

  • projectIdstringrequired

    The ID of the project

  • roleNamestringrequired

    The name of the role

Request body application/json

  • titlestring

    The title of the role

    Example:Translator
  • descriptionstring

    The description of the role

    Example:Edit translated documents
  • appliesToUsersboolean

    Whether the role applies to users. You can't set it to false while users have the role.

    Example:true
  • appliesToRobotsboolean

    Whether the role applies to robots. You can't set it to false while robots have the role.

    Example:false
Examplesapplication/json
{
  "title": "Translator",
  "description": "Edit and review translated documents"
}

Responses

200

OK

  • namestring

    The role name

    Example:administrator
  • titlestring

    The role title

    Example:Administrator
  • descriptionstring

    A description of the role's permissions. An empty string if the role has no description.

    Example:Read and write access to all datasets, with full access to all project settings.
  • isCustomboolean

    Whether this is a custom role

    Example:false
  • projectIdstring

    The ID of the project this role belongs to

    Example:3do82whm
  • appliesToUsersboolean

    Whether the role can be given to users

    Example:true
  • appliesToRobotsboolean

    Whether the role can be given to robots

    Example:false
  • grantsobject

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Examplesapplication/json
{
  "name": "translator",
  "title": "Translator",
  "description": "Edit and review translated documents",
  "isCustom": true,
  "projectId": "3do82whm",
  "appliesToUsers": true,
  "appliesToRobots": false,
  "grants": {
    "sanity.document.filter": [
      {
        "id": "res-k2d8fj3a",
        "name": "articles",
        "title": "Articles",
        "description": "Documents of type article",
        "isCustom": true,
        "config": {
          "filter": "_type == \"article\""
        },
        "grants": [
          {
            "name": "read",
            "params": {}
          },
          {
            "name": "update",
            "params": {}
          }
        ]
      }
    ]
  }
}

Organization

Endpoints for managing organization-level roles and permissions

List organization members

get/organizations/{organizationId}/acl

Get a list of all members and their roles in an organization. Requires the read permission on sanity.organization.members.

The list only includes roles given directly to members. Roles a member gets through project membership aren't listed.

Path parameters

Query parameters

  • roles[]array

    Only return members who have at least one of these roles. Use the roles[] form, for example ?roles[]=administrator.

    A single plain ?roles=administrator returns 400 with the message roles must be an array.

    items
    • itemsstring

Responses

200

List of organization members and their roles

    items
    • sanityUserIdstring

      The Sanity user ID

      Example:g...
    • rolesarray
      Example
      [{"name":"administrator","title":"Administrator"}]
      Show child attributes
      items
      • namestring

        The role name

        Example:administrator
      • titlestring

        The role title

        Example:Administrator
Examplesapplication/json
[
  {
    "sanityUserId": "g...",
    "roles": [
      {
        "name": "administrator",
        "title": "Administrator"
      }
    ]
  },
  {
    "sanityUserId": "g...",
    "roles": [
      {
        "name": "administrator",
        "title": "Administrator"
      }
    ]
  }
]

Get the roles of a single organization member

get/organizations/{organizationId}/acl/{sanityUserId}

Get the roles of a specific member in an organization. Requires the read permission on sanity.organization.members.

Path parameters

Responses

200

Member roles information

  • sanityUserIdstring

    The Sanity user ID

    Example:g...
  • rolesarray
    Example
    [{"name":"administrator","title":"Administrator"}]
    Show child attributes
    items
    • namestring

      The role name

      Example:administrator
    • titlestring

      The role title

      Example:Administrator
Examplesapplication/json
{
  "sanityUserId": "g...",
  "roles": [
    {
      "name": "administrator",
      "title": "Administrator"
    }
  ]
}

Give an organization member a role

put/organizations/{organizationId}/acl/{sanityUserId}

Add a role to an existing member of an organization. You can't use this endpoint to add new members. Requires the update permission on sanity.organization.members.

Set deleteExistingRoles to true to also remove the member's other roles in the organization. When you do, the request fails if it would leave the organization without an administrator.

Path parameters

Request body application/json

  • roleNamestringrequired

    The name of the role to assign

    Example:administrator
  • deleteExistingRolesbooleandefault: false

    Remove the member's other roles in the organization

Examplesapplication/json
{
  "roleName": "administrator"
}

Responses

200

The member already had this role. If deleteExistingRoles is true, the member's other roles are still removed. The response has no body.

Remove a role from an organization member

delete/organizations/{organizationId}/acl/{sanityUserId}

Remove a role from a member in an organization. Send roleName to remove one role. Omit roleName to remove all of the member's roles, which removes the member from the organization. Requires the update permission on sanity.organization.members.

An organization must keep at least one administrator.

Path parameters

Request body application/json

  • roleNamestring

    The name of the role to remove. Omit it to remove all of the user's roles.

    Example:editor
Examplesapplication/json
{
  "roleName": "administrator"
}

Responses

200

Role removed successfully

  • object
Examplesapplication/json
{}

Get all grants for current user

get/organizations/{organizationId}/grants

Get all grants for the current user in an organization, including grants from roles the user gets through project membership. The user must be a member of the organization.

Path parameters

Responses

200

Grants for the current user, grouped by permission resource type

  • object

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Create an organization grant

post/organizations/{organizationId}/grants

Add a grant to a custom role in an organization. A grant gives the role a permission on a permission resource. Identify the resource with permissionResourceId or permissionResourceName.

You can only add grants to custom roles. Requests for a built-in role return 400 with the message Can not modify grants on a non-custom role. Requires the update permission on sanity.organization.roles.

Path parameters

Request body application/json

Examplesapplication/json
{
  "roleName": "custom-role",
  "permissionName": "read",
  "permissionResourceId": "res-k2d8fj3a"
}

Responses

200

The grant already existed, or its parameters were updated. Returns the grant configuration.

  • roleNamestring

    The name of the role

    Example:translator
  • permissionNamestring

    The name of the permission

    Example:read
  • permissionResourceTypestring

    The name of the permission resource schema

    Example:sanity.document.filter
  • permissionResourceIdstring

    The ID of the permission resource

    Example:res-k2d8fj3a
  • paramsobject

    The permission parameters

    Example
    {}
  • tagIdstring|null

    Only returned when you remove a project grant. The ID of the tag the grant applied to, if any.

  • datasetIdstring|null

    Only returned when you remove a project grant. The ID of the dataset the grant applied to, if any.

Remove an organization grant

delete/organizations/{organizationId}/grants

Remove a grant from a custom role in an organization. The request body has the same shape as when you create an organization grant. You can only remove grants from custom roles. Requires the update permission on sanity.organization.roles.

A grant only matches if params is exactly the same as when the grant was created. If nothing matches, the request still returns 200 with deletedGrants set to 0.

Path parameters

Request body application/json

Examplesapplication/json
{
  "roleName": "custom-role",
  "permissionName": "read",
  "permissionResourceId": "res-k2d8fj3a"
}

Responses

200

Returns the number of grants removed

Examplesapplication/json
{
  "deletedGrants": 1
}

Create/update project role mappings

put/auth/organizations/{organizationId}/providers/{providerId}/projects/{projectId}/role-mappings

Create, update, or delete project role mappings for SAML SSO. The request changes only the mappings it names; other mappings are left alone.

  • An item without id creates a new mapping. Sending the same item twice creates two mappings.
  • An item with id, roleName, and groupRule updates that mapping.
  • An item with id and an empty or null roleName and groupRule deletes that mapping.
  • fallbackRoleName sets the role for users who match no mapping. Set it to null to remove the fallback, or omit it to leave the fallback unchanged.

Sending roleMappings requires the project to have the authSAMLRoleMapping feature. Setting only fallbackRoleName doesn't.

Robot Tokens

This endpoint cannot be accessed using robot tokens.

Authorization

Requires the saml permission for the sanity.organization.sso resource. Send the token in the Authorization header; session cookies aren't accepted.

Path parameters

Request body application/json

  • fallbackRoleNamestring|null

    The role for users who match no mapping. Set to null to remove the fallback. Omit to leave it unchanged.

    Example:viewer
  • roleMappingsarray
    Show child attributes
    items
    • idstring

      The ID of an existing role mapping, as returned by this endpoint. Omit it to create a new mapping.

    • roleNamestring|null

      The name of a Sanity role to assign. Required unless you're deleting the mapping.

      Example:editor
    • groupRulestring|null

      A regular expression matched against the user's SAML groups. Required unless you're deleting the mapping.

      Example:.*-admin
Examplesapplication/json
{
  "fallbackRoleName": "viewer",
  "roleMappings": [
    {
      "roleName": "editor",
      "groupRule": ".*-admin"
    }
  ]
}

Responses

200

Role mappings created or updated. Returns the mappings the request created or updated, including the fallback mapping.

    items
    • idstring

      The ID of the role mapping

    • roleNamestring

      The name of the Sanity role

      Example:editor
    • groupRulestring

      The group rule. The fallback mapping uses the reserved value _.*.sanity.fallback.

      Example:.*-admin

Delete project role mappings

delete/auth/organizations/{organizationId}/providers/{providerId}/projects/{projectId}/role-mappings

Deletes all project role mappings for a specific SSO provider and project within an organization, including the fallback mapping. For use with SAML SSO implementations.

Authorization

Requires the saml permission for the sanity.organization.sso resource. Send the token in the Authorization header; session cookies aren't accepted.

Path parameters

Responses

200

Role mappings deleted successfully

  • object
Examplesapplication/json
{}

Dataset

Endpoints for managing dataset-level access control and grants

Get dataset ACL

get/projects/{projectId}/datasets/{datasetName}/acl

Get the access control list for a dataset, as it applies to the caller. Each entry pairs a GROQ filter with the permissions granted on documents that match it. Filters that use user::attributes() are resolved for the current user.

This endpoint doesn't require a token. Without one, it returns only the entries that apply to everyone.

Path parameters

Responses

200

Dataset ACL information

    items
    • filterstring

      The filter for the ACL

      Example:_id in path("**")
    • permissionsarray

      The permissions granted on documents matching the filter

      Example
      ["read","update","create","history"]
      Show child attributes
      items
      • string
        enum:"read", "update", "create", "history"
Examplesapplication/json
[
  {
    "filter": "_id in path(\"**\")",
    "permissions": [
      "read",
      "update",
      "create",
      "history"
    ]
  }
]

Get dataset grants

get/projects/{projectId}/datasets/{datasetName}/grants

Get the current user's document grants for a dataset. The user must be a member of the project.

Path parameters

Responses

200

The current user's document grants, grouped by permission resource type. Returns an empty object if the user has no roles.

  • object

    Grants grouped by permission resource schema name, such as sanity.project or sanity.document.filter.mode.

Examplesapplication/json
{
  "sanity.document.filter.mode": [
    {
      "id": "res-7hd3kq9z",
      "name": "sanity-all-documents",
      "title": "All documents",
      "description": null,
      "isCustom": false,
      "config": {
        "filter": "_id in path(\"**\")"
      },
      "grants": [
        {
          "name": "mode",
          "params": {
            "mode": "publish",
            "history": true
          }
        }
      ]
    }
  ]
}
sanity.ioAll Systems Operational© Sanity 2026
Change site theme