HTTP API Reference

Access API reference

A centralized API to manage resource access control through roles and permissions.

A centralized API to manage resource access control through roles and permissions.

Want to get started?

Roles user guide

Configuring roles and permissions in the manage interface

Authentication

  • All requests must be authenticated.
  • See the individual endpoints below for required usage permissions.

Terms

Throughout this document the terms {resourceType} and {resourceId} refer to the resource the API request is being applied to.

  • {resourceType} can be an organization or project.
  • {resourceId} is the ID of the resource the API request affects.

When a client uses this API, it acts in the context of a specific resource. For example:

  • https://api.sanity.io/v2025-07-11/access/organization/or0Bc1hcJ/roles
  • https://api.sanity.io/v2025-07-11/access/project/c7ja4siy/roles

Key concepts

Resource

A resource is an entity that can be managed and accessed through the API. Currently, the supported resources are organization and project.

Permission

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

A role is a named collection of permissions that can be applied to a user or robot. Roles are in the scope of a resource and can only receive permissions that are in the same resource scope. For example, a project role can only include document permissions for that project.

A role is specific to a single resource and can only include permissions within that resource's scope. In the future, roles will be able to include permissions for child resources as well. For example, an organization role will be able to include document permissions for specific projects or all projects.

A user cannot be part of a resource without a role. Each user in an organization must have at least one role assigned to them.

There are both pre-defined and custom roles. Pre-defined roles are included with the product and are not editable, but can be removed from a resource if the feature is enabled.

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 (e.g., 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.

Administrator Rules

Changing Administrators

Only administrators can assign or remove roles with admin permissions. This prevents unauthorized permission elevation.

This rule applies only to the default roles. Custom roles are fully managed by the organization and can be assigned to users without restriction.

Last Administrator

Each resource must have at least one role assigned to at least one user that can read users, read roles, and assign roles to users. This prevents an organization from losing control over their resources.

This is designed as a permission-level check and not a role-level check, so that the default roles can be removed from a resource. Customers with advanced roles management enabled can remove the default roles from a resource.

Breaking Changes from previous versions

See the details of the existing API for a better understanding of the changes.

Summary:

  • Access is now the root path for managing access-based resources. Previously it was organization and project but these are now nested under the access root.
  • Internal IDs are no longer exposed for permissions or roles. The name property is now used as the unique identifier for permissions and roles.
  • Permissions now represent grants, resources, and permissionResourceSchema. These are now legacy terms.
  • The endpoint /organization/:organizationId/users returns users for all resources owned by the organization. Previously, a client would have to make a request for each resource (e.g., project) individually.
  • users replaces the term ACL. Users represents individuals assigned roles within the organization.
  • The pre-defined roles can be completely removed from a resource. Previously, default roles could not be removed from a resource. E.g., a project required at least one project administrator, even if there were custom roles that would cover the same use case.

Base API server URL

Production External API

https://api.sanity.io

Users

Manage users who have been assigned organization roles.

List all users of a resource and their assigned roles.

get/v2025-07-11/access/{resourceType}/{resourceId}/users

Retrieve a list of all users of a resource along with their assigned roles. When the resourceType is organization, this endpoint will return users of projects owned by the organization. Requires permission

  • sanity.{resourceType}.members.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

  • includeImpliedRolesbooleandefault: false

    Whether to include implied roles in the response.

  • sortBystring

    Field by which to sort result. Currently supports field 'displayName'

    Example:displayName
  • orderBystring

    In which order to list results

    Example:desc
  • emailstring

    Filter results based on email match

  • displayNamestring

    Filter results based on displayName match

Responses

200

A paginated list of resource users and their assigned roles

  • dataarrayrequired
    Show child attributes
    items
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

  • totalCountintegerrequired

    Total number of users available

    Example:1

Apply organization default role to all users.

put/v2025-07-11/access/organization/{resourceId}/users/roles/default

Add default role to all resource users. Limited to Organization. Requires permission

  • sanity.organization.members.update

Path parameters

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Responses

201

Roles assigned to the resource users

Get user and roles.

get/v2025-07-11/access/{resourceType}/{resourceId}/users/{sanityUserId}

Get the users for a single user of a resource. Requires permission - sanity.{resourceType}.members.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • sanityUserIdstringrequired

    The User ID

    Example:gDdcnv42e

Query parameters

Responses

200

Get resource user and their roles.

Remove a user from a resource.

delete/v2025-07-11/access/{resourceType}/{resourceId}/users/{sanityUserId}

This removes all roles. If the resourceType is organization, this will also remove the user from all projects owned by the organization. Requires permission

  • sanity.{resourceType}.members.delete

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • sanityUserIdstringrequired

    The User ID

    Example:gDdcnv42e

Responses

200

User removed from the resource

Remove own user from a resource.

delete/v2025-07-11/access/{resourceType}/{resourceId}/users/me

This removes the currently authenticated user from the given resource. If the resourceType is organization, this will also remove the user from all projects owned by the organization. This is a specific route which does not require resource permissions, since users should be able to remove themselves from resources without requiring an administrator to intervene for them.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Responses

200

User removed from the resource

Add a role to a user.

put/v2025-07-11/access/{resourceType}/{resourceId}/users/{sanityUserId}/roles/{roleName}

Add a role to a user. Requires permission

  • sanity.{resourceType}.members.update

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • sanityUserIdstringrequired

    The User ID

    Example:gDdcnv42e
  • roleNamestringrequired

    The role name.

    Example:administrator

Responses

201

Role assigned to the user

Remove a role from a user in a resource.

delete/v2025-07-11/access/{resourceType}/{resourceId}/users/{sanityUserId}/roles/{roleName}

You cannot remove the last role from a user. You must have at least one role assigned to a user. Requires permission

  • sanity.{resourceType}.members.update

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • sanityUserIdstringrequired

    The User ID

    Example:gDdcnv42e
  • roleNamestringrequired

    The role name.

    Example:administrator

Responses

200

Role removed from user

Robots

Manage robots and robot tokens.

Get robots with access to this resource

get/v2025-07-11/access/{resourceType}/{resourceId}/robots

Retrieves a list of robots that have access to the specified resource.

Access to children resources

By default, this endpoint returns robots that have at least one role on the specified resource. Use the optional includeChildren parameter to include robots that have a role on children resources as well. This only applies to organization resources.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.tokens.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • includeChildrenboolean

    Whether to include children resources in the response. Only applies to organization resources.

    Example:false
  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

Responses

200

A paginated list of robots

  • dataarrayrequired
    Show child attributes
    items
    • idstringrequired

      The unique identifier for the robot.

    • tokenIdstring

      The unique identifier for the active token.

    • labelstringrequired

      A human-readable label for the robot.

    • createdAtstring (date-time)required

      The creation date of the robot.

    • expiresAtstring (date-time)

      When the active token expires.

    • membershipsarrayrequired
      Show child attributes
      items
      • addedAtstring (date-time)
        Example:2024-01-15T12:15:30Z
      • resourceTypestringrequired
        Example:project
      • resourceIdstringrequired
        Example:c7ja4siy
      • roleNamesarrayrequired
        Example
        ["administrator","editor"]
        Show child attributes
        items
        • string
      • lastSeenAtstring (date-time) | null
        Example:2024-01-15T12:15:30Z
      • resourceUserIdstring | null

        An alternative ID for the user in the resource. Only present for project memberships. That is, a user can be assigned to multiple projects, and each project will have a different resourceUserId to reference the same user.

        Example:projectUserId123
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

Create robot and associated token

post/v2025-07-11/access/{resourceType}/{resourceId}/robots

Creates a robot with the specified role grants and returns its secret token.

Only the specified resource and its children resources can be specified in the role grants. The robot will not have access to other resources.

Secret token

The secret token is only returned once and can not be retrieved again. If the token is lost, a new robot must be created. The previous robot should be deleted.

Email notifications

For project robots, an email notification is sent to all project administrators by default when a robot is created. This can be disabled by setting sendNotification=false, but only for projects created within the last 5 minutes.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.tokens.create

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • sendNotificationbooleandefault: true

    Whether to send email notification to administrators when creating project robots. Only applies to project resource types. Can be set to false for projects created within the last 5 minutes.

    Example:true

Request body application/json

  • labelstringrequired

    A human-readable label for the robot.

    Example:My Robot
  • expiresAtstring (date-time)

    When the token should expire.

    Example:2030-01-01T00:00:00.000Z
  • membershipsarrayrequired
    Show child attributes
    items
    • addedAtstring (date-time)
      Example:2024-01-15T12:15:30Z
    • resourceTypestringrequired
      Example:project
    • resourceIdstringrequired
      Example:c7ja4siy
    • roleNamesarrayrequired
      Example
      ["administrator","editor"]
      Show child attributes
      items
      • string
    • lastSeenAtstring (date-time) | null
      Example:2024-01-15T12:15:30Z
    • resourceUserIdstring | null

      An alternative ID for the user in the resource. Only present for project memberships. That is, a user can be assigned to multiple projects, and each project will have a different resourceUserId to reference the same user.

      Example:projectUserId123

Responses

201

Robot created.

  • tokenstringrequired

    The secret token for the robot.

  • idstringrequired

    The unique identifier for the robot.

  • tokenIdstring

    The unique identifier for the active token.

  • labelstringrequired

    A human-readable label for the robot.

  • createdAtstring (date-time)required

    The creation date of the robot.

  • expiresAtstring (date-time)

    When the active token expires.

  • membershipsarrayrequired
    Show child attributes
    items
    • addedAtstring (date-time)
      Example:2024-01-15T12:15:30Z
    • resourceTypestringrequired
      Example:project
    • resourceIdstringrequired
      Example:c7ja4siy
    • roleNamesarrayrequired
      Example
      ["administrator","editor"]
      Show child attributes
      items
      • string
    • lastSeenAtstring (date-time) | null
      Example:2024-01-15T12:15:30Z
    • resourceUserIdstring | null

      An alternative ID for the user in the resource. Only present for project memberships. That is, a user can be assigned to multiple projects, and each project will have a different resourceUserId to reference the same user.

      Example:projectUserId123

Get robot metadata

get/v2025-07-11/access/{resourceType}/{resourceId}/robots/{robotId}

Retrieves a robot using its unique identifier.

It's not possible to retrieve a robot token.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.tokens.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • robotIdstringrequired

    The robot's unique identifier.

    Example:gJh7daoq4

Responses

200

Robot found.

  • idstringrequired

    The unique identifier for the robot.

  • tokenIdstring

    The unique identifier for the active token.

  • labelstringrequired

    A human-readable label for the robot.

  • createdAtstring (date-time)required

    The creation date of the robot.

  • expiresAtstring (date-time)

    When the active token expires.

  • membershipsarrayrequired
    Show child attributes
    items
    • addedAtstring (date-time)
      Example:2024-01-15T12:15:30Z
    • resourceTypestringrequired
      Example:project
    • resourceIdstringrequired
      Example:c7ja4siy
    • roleNamesarrayrequired
      Example
      ["administrator","editor"]
      Show child attributes
      items
      • string
    • lastSeenAtstring (date-time) | null
      Example:2024-01-15T12:15:30Z
    • resourceUserIdstring | null

      An alternative ID for the user in the resource. Only present for project memberships. That is, a user can be assigned to multiple projects, and each project will have a different resourceUserId to reference the same user.

      Example:projectUserId123

Update robot token

put/v2025-07-11/access/{resourceType}/{resourceId}/robots/{robotId}

Updates the expiry date for a robot token.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.tokens.create

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • robotIdstringrequired

    The robot's unique identifier.

    Example:gJh7daoq4

Request body application/json

  • expiresAtstring (date-time)required

    When the robot token should expire.

    Example:2030-01-01T00:00:00.000Z

Responses

200

Robot token expiry updated.

  • idstringrequired

    The unique identifier for the robot.

  • tokenIdstring

    The unique identifier for the active token.

  • labelstringrequired

    A human-readable label for the robot.

  • createdAtstring (date-time)required

    The creation date of the robot.

  • expiresAtstring (date-time)

    When the active token expires.

  • membershipsarrayrequired
    Show child attributes
    items
    • addedAtstring (date-time)
      Example:2024-01-15T12:15:30Z
    • resourceTypestringrequired
      Example:project
    • resourceIdstringrequired
      Example:c7ja4siy
    • roleNamesarrayrequired
      Example
      ["administrator","editor"]
      Show child attributes
      items
      • string
    • lastSeenAtstring (date-time) | null
      Example:2024-01-15T12:15:30Z
    • resourceUserIdstring | null

      An alternative ID for the user in the resource. Only present for project memberships. That is, a user can be assigned to multiple projects, and each project will have a different resourceUserId to reference the same user.

      Example:projectUserId123

Delete robot and associated token

delete/v2025-07-11/access/{resourceType}/{resourceId}/robots/{robotId}

Deletes a robot and revokes its token.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.tokens.delete

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • robotIdstringrequired

    The robot's unique identifier.

    Example:gJh7daoq4

Responses

204

Robot deleted.

Roles

Manage roles assignable to users of an organization or application.

List roles assignable to a user on this resource.

get/v2025-07-11/access/{resourceType}/{resourceId}/roles

Requires permission

  • sanity.{resourceType}.roles.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • includeChildrenboolean

    Whether to include children resources in the response. Only applies to organization resources.

    Example:false
  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

  • includeImpliedRolesbooleandefault: false

    Whether to include implied roles in the response.

Responses

200

A paginated list of roles for a resource

  • dataarrayrequired
    Show child attributes
    items
    • namestringrequired
      Example:administrator
    • titlestringrequired
      Example:Administrator
    • descriptionstring
      Example:Administrators can manage billing details, legal contacts, organization users, and manage project ownership.
    • isCustomboolean
      Example:false
    • resourceTypestringrequired
      Example:organization
    • resourceIdstringrequired
      Example:or0Bc1hcJ
    • appliesToUsersbooleanrequired
      Example:true
    • appliesToRobotsbooleanrequired
      Example:true
    • permissionsarrayrequired
      Show child attributes
      items
      • typestring

        The resource for the permission.

        Example:sanity.document.filter.mode
      • action
        Show child attributes
        • string
          enum:"create", "read", "update", "manage", "history", "editHistory"
      • namestring

        The name of the permission.

        Example:legal-documents
      • paramsobject

        The parameters for the permission. This is a key-value map of the permission's configuration.

        Example
        {"dataset":"development"}
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

Create a role

post/v2025-07-11/access/{resourceType}/{resourceId}/roles

Requires permission:

  • sanity.{resourceType}.roles.create Requires feature:
  • advancedRolesManagement

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Request body application/json

  • titlestringrequired
    Example:Custom Role
  • namestringrequired
    Example:custom-role
  • descriptionstringdefault: ""
    Example:Custom role for project
  • appliesToUsersbooleandefault: truerequired
  • appliesToRobotsbooleandefault: truerequired
  • permissionsarrayrequired
    Show child attributes
    items
    • namestring

      The name of the permission.

      Example:legal-documents
    • action
      Show child attributes
      • string
        enum:"create", "read", "update", "manage", "history", "editHistory"
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"dataset":"development"}

Responses

201

Role created

  • namestringrequired
    Example:administrator
  • titlestringrequired
    Example:Administrator
  • descriptionstring
    Example:Administrators can manage billing details, legal contacts, organization users, and manage project ownership.
  • isCustomboolean
    Example:false
  • resourceTypestringrequired
    Example:organization
  • resourceIdstringrequired
    Example:or0Bc1hcJ
  • appliesToUsersbooleanrequired
    Example:true
  • appliesToRobotsbooleanrequired
    Example:true
  • permissionsarrayrequired
    Show child attributes
    items
    • typestring

      The resource for the permission.

      Example:sanity.document.filter.mode
    • action
      Show child attributes
      • string
        enum:"create", "read", "update", "manage", "history", "editHistory"
    • namestring

      The name of the permission.

      Example:legal-documents
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"dataset":"development"}

Get a role

get/v2025-07-11/access/{resourceType}/{resourceId}/roles/{roleName}

Requires permission

  • sanity.{resourceType}.roles.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • roleNamestringrequired

    The role name.

    Example:administrator

Responses

200

Get a role

  • namestringrequired
    Example:administrator
  • titlestringrequired
    Example:Administrator
  • descriptionstring
    Example:Administrators can manage billing details, legal contacts, organization users, and manage project ownership.
  • isCustomboolean
    Example:false
  • resourceTypestringrequired
    Example:organization
  • resourceIdstringrequired
    Example:or0Bc1hcJ
  • appliesToUsersbooleanrequired
    Example:true
  • appliesToRobotsbooleanrequired
    Example:true
  • permissionsarrayrequired
    Show child attributes
    items
    • typestring

      The resource for the permission.

      Example:sanity.document.filter.mode
    • action
      Show child attributes
      • string
        enum:"create", "read", "update", "manage", "history", "editHistory"
    • namestring

      The name of the permission.

      Example:legal-documents
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"dataset":"development"}

Update a role

put/v2025-07-11/access/{resourceType}/{resourceId}/roles/{roleName}

Requires permission:

  • sanity.{resourceType}.roles.update

Requires feature:

  • advancedRolesManagement

Replaces existing object values including permissions.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • roleNamestringrequired

    The role name.

    Example:administrator

Request body application/json

  • titlestringrequired
    Example:Custom Role
  • namestringrequired
    Example:custom-role
  • descriptionstringdefault: ""
    Example:Custom role for project
  • appliesToUsersbooleandefault: truerequired
  • appliesToRobotsbooleandefault: truerequired
  • permissionsarrayrequired
    Show child attributes
    items
    • namestring

      The name of the permission.

      Example:legal-documents
    • action
      Show child attributes
      • string
        enum:"create", "read", "update", "manage", "history", "editHistory"
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"dataset":"development"}

Responses

200

Role updated

  • namestringrequired
    Example:administrator
  • titlestringrequired
    Example:Administrator
  • descriptionstring
    Example:Administrators can manage billing details, legal contacts, organization users, and manage project ownership.
  • isCustomboolean
    Example:false
  • resourceTypestringrequired
    Example:organization
  • resourceIdstringrequired
    Example:or0Bc1hcJ
  • appliesToUsersbooleanrequired
    Example:true
  • appliesToRobotsbooleanrequired
    Example:true
  • permissionsarrayrequired
    Show child attributes
    items
    • typestring

      The resource for the permission.

      Example:sanity.document.filter.mode
    • action
      Show child attributes
      • string
        enum:"create", "read", "update", "manage", "history", "editHistory"
    • namestring

      The name of the permission.

      Example:legal-documents
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"dataset":"development"}

Delete a role

delete/v2025-07-11/access/{resourceType}/{resourceId}/roles/{roleName}

Requires permission:

  • sanity.{resourceType}.roles.delete for resource scoped roles (e.g. project admin)

Requires feature:

  • advancedRolesManagement

Cannot delete a role that is assigned to a user. The role needs to be removed from users first.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • roleNamestringrequired

    The role name.

    Example:administrator

Responses

200

Role deleted

Permissions

View permissions available to roles within an organization or application.

Get Permissions.

get/v2025-07-11/access/{resourceType}/{resourceId}/permissions

Gets the available permissions within the scope of a resource. These permissions can be applied to roles and are used to determine user/robot access to resources.

Requires permission: sanity.{resourceType}.roles.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

Responses

200

A paginated list of permission resources for the resource

  • dataarrayrequired
    Show child attributes
    items
    • typestringrequired

      The resource for the permission.

      Example:sanity.document.filter.mode
    • actions

      The actions allowed by the permission for this role.

      Example:["mode"]
      Show child attributes
        items
        • namestring
        • titlestring
          Example:Sanity Document Filter
        • descriptionstring
          Example:Defines a permission resource for a filtered collection of Sanity documents
    • namestringrequired

      The name of the permission. This is the unique identifier for the resource.

      Example:legal-documents
    • titlestringrequired

      The human-readable title of the permission.

      Example:Permission for "Legal" Folder
    • descriptionstring

      The description of the permission.

      Example:Permission for "Legal" Folder
    • resourceTypestringrequired

      The resource the permission applies to.

      Example:project
    • resourceIdstringrequired

      The resource ID the permission applies to.

      Example:c7ja4siy
    • ownerOrganizationIdstring

      The organization ID the permission applies to. Used for wildcard permissions where the resourceId is *.

      Example:or0Bc1hcJ
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"filter":"*[_type == \"legal\"]"}
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

Create a permission.

post/v2025-07-11/access/{resourceType}/{resourceId}/permissions

Creates a custom permission on a resource.

Requires permission: sanity.{resourceType}.roles.create
Requires feature: advancedRolesManagement

See Example. It creates a permission to allow a user to read legal documents in project c7ja4siy and dataset production.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Request body application/json

  • typestringrequired

    The resource for the permission.

    Example:sanity.document.filter.mode
  • namestringrequired

    The name of the permission resource. A unique identifier for a permission.

    Example:legal-documents
  • titlestringrequired

    A human-readable title of the permission resource. This is used for display purposes.

    Example:Permission for "Legal" Folder
  • descriptionstringrequired

    The description of the permission resource.

    Example:Permission for "Legal" Folder
  • configobject

    Some permissions allow for additional configuration when used with document permissions. Accepts a groq filter or a dataset name.

    Example
    {"filter":"*[_type == 'legal']"}

Responses

201

Permission resource created successfully

  • typestringrequired

    The resource for the permission.

    Example:sanity.document.filter.mode
  • actions

    The actions allowed by the permission for this role.

    Example:["mode"]
    Show child attributes
      items
      • namestring
      • titlestring
        Example:Sanity Document Filter
      • descriptionstring
        Example:Defines a permission resource for a filtered collection of Sanity documents
  • namestringrequired

    The name of the permission. This is the unique identifier for the resource.

    Example:legal-documents
  • titlestringrequired

    The human-readable title of the permission.

    Example:Permission for "Legal" Folder
  • descriptionstring

    The description of the permission.

    Example:Permission for "Legal" Folder
  • resourceTypestringrequired

    The resource the permission applies to.

    Example:project
  • resourceIdstringrequired

    The resource ID the permission applies to.

    Example:c7ja4siy
  • ownerOrganizationIdstring

    The organization ID the permission applies to. Used for wildcard permissions where the resourceId is *.

    Example:or0Bc1hcJ
  • paramsobject

    The parameters for the permission. This is a key-value map of the permission's configuration.

    Example
    {"filter":"*[_type == \"legal\"]"}

Get a permission

get/v2025-07-11/access/{resourceType}/{resourceId}/permissions/{permissionName}

Gets a permission for a resource by name. Requires permission

  • sanity.{resourceType}.roles.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • permissionNamestringrequired

    The name of the permission. This is a unique identifier for the permission.

    Example:sanity.project.members.read

Responses

200

The permission resource for the resource

  • typestringrequired

    The resource for the permission.

    Example:sanity.document.filter.mode
  • actions

    The actions allowed by the permission for this role.

    Example:["mode"]
    Show child attributes
      items
      • namestring
      • titlestring
        Example:Sanity Document Filter
      • descriptionstring
        Example:Defines a permission resource for a filtered collection of Sanity documents
  • namestringrequired

    The name of the permission. This is the unique identifier for the resource.

    Example:legal-documents
  • titlestringrequired

    The human-readable title of the permission.

    Example:Permission for "Legal" Folder
  • descriptionstring

    The description of the permission.

    Example:Permission for "Legal" Folder
  • resourceTypestringrequired

    The resource the permission applies to.

    Example:project
  • resourceIdstringrequired

    The resource ID the permission applies to.

    Example:c7ja4siy
  • ownerOrganizationIdstring

    The organization ID the permission applies to. Used for wildcard permissions where the resourceId is *.

    Example:or0Bc1hcJ
  • paramsobject

    The parameters for the permission. This is a key-value map of the permission's configuration.

    Example
    {"filter":"*[_type == \"legal\"]"}

Update a permission

put/v2025-07-11/access/{resourceType}/{resourceId}/permissions/{permissionName}

Updates a permission for a resource. Requires permission

  • sanity.{resourceType}.roles.update Requires feature:
  • advancedRolesManagement

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • permissionNamestringrequired

    The name of the permission. This is a unique identifier for the permission.

    Example:sanity.project.members.read

Request body application/json

  • typestringrequired

    The resource for the permission.

    Example:sanity.document.filter.mode
  • namestringrequired

    The name of the permission resource. A unique identifier for a permission.

    Example:legal-documents
  • titlestringrequired

    A human-readable title of the permission resource. This is used for display purposes.

    Example:Permission for "Legal" Folder
  • descriptionstringrequired

    The description of the permission resource.

    Example:Permission for "Legal" Folder
  • configobject

    Some permissions allow for additional configuration when used with document permissions. Accepts a groq filter or a dataset name.

    Example
    {"filter":"*[_type == 'legal']"}

Responses

200

Permission resource updated successfully

  • typestringrequired

    The resource for the permission.

    Example:sanity.document.filter.mode
  • actions

    The actions allowed by the permission for this role.

    Example:["mode"]
    Show child attributes
      items
      • namestring
      • titlestring
        Example:Sanity Document Filter
      • descriptionstring
        Example:Defines a permission resource for a filtered collection of Sanity documents
  • namestringrequired

    The name of the permission. This is the unique identifier for the resource.

    Example:legal-documents
  • titlestringrequired

    The human-readable title of the permission.

    Example:Permission for "Legal" Folder
  • descriptionstring

    The description of the permission.

    Example:Permission for "Legal" Folder
  • resourceTypestringrequired

    The resource the permission applies to.

    Example:project
  • resourceIdstringrequired

    The resource ID the permission applies to.

    Example:c7ja4siy
  • ownerOrganizationIdstring

    The organization ID the permission applies to. Used for wildcard permissions where the resourceId is *.

    Example:or0Bc1hcJ
  • paramsobject

    The parameters for the permission. This is a key-value map of the permission's configuration.

    Example
    {"filter":"*[_type == \"legal\"]"}

Delete a permission

delete/v2025-07-11/access/{resourceType}/{resourceId}/permissions/{permissionName}

Deletes a specific permission for a resource. Can only be used with custom permissions. Requires permission

  • sanity.{resourceType}.roles.delete Requires feature:
  • advancedRolesManagement

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • permissionNamestringrequired

    The name of the permission. This is a unique identifier for the permission.

    Example:sanity.project.members.read

Responses

200

Permission deleted successfully

Get current user permissions.

get/v2025-07-11/access/{resourceType}/{resourceId}/user-permissions/me

Gets current user permissions within scope of a resource. These permissions can be applied to roles and are used to determine user/robot access to resources.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

Responses

200

A paginated list of permissions for all resources the current user has access to

  • dataarrayrequired
    Show child attributes
    items
    • namestringrequired

      The name of the permission.

      Example:sanity-project-members
    • typestring

      The type of the permission.

      Example:sanity.project.members
    • actionrequired
      Show child attributes
      • string
        enum:"create", "read", "update", "manage", "history", "editHistory"
    • resourceTypestringrequired

      Resources are entities that can be managed and accessed through the Access API.

      Example:project
    • resourceIdstringrequired
      Example:project-id
    • paramsobject

      The parameters for the permission. This is a key-value map of the permission's configuration.

      Example
      {"dataset":"development"}
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

Check if current user has specified permissions

get/v2025-07-11/access/{resourceType}/{resourceId}/user-permissions/me/check

Checks if the current user has the specified permissions for the given resource. Returns an object mapping each requested permission to a boolean indicating whether the user has that permission.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • permissionsarrayrequired

    An array of permissions to check

    items
    • itemsstring

Responses

200

Map of permissions to whether the user has them

  • dataobjectrequired
    Example
    {"sanity.project.members.read":true,"sanity.project.members.invite":false}

Requests

Request access to resources. View requests to access resources.

List all requests for given project/organization.

get/v2024-07-01/access/{resourceType}/{resourceId}/requests

Permissions sanity.{resourceType}.members.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • includeChildrenboolean

    Whether to include children resources in the response. Only applies to organization resources.

    Example:false

Responses

200

A list of resource requests

Create a new Request

post/v2024-07-01/access/{resourceType}/{resourceId}/requests

Creates a new request for the given project/organization. Requires an authenticated user.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Request body application/json

  • notestring
    Example:Text describing the reason of the request
  • requestUrlstring

    Optional URL to redirect the user to after their request has been accepted. Do not include PII or other confidential information.

    Example:https://sanity-studio.mycompany.io/doc/1234567890
  • requestedRolestring

    Optional role requested by the user. The approver can assign a different role, but this is just a suggestion. If the role does not exist, the request will still be created and no validation on the role will be done.

    Example:editor
  • typestring

    The type of request.

    Example:access

Responses

201

Request created successfully

Accept request

put/v2024-07-01/access/{resourceType}/{resourceId}/requests/{requestId}/accept

Permissions sanity.{resourceType}.members.invite

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • requestIdstringrequired

    The ID of the request.

Request body application/json

  • roleNamesarray
    Show child attributes
    items
    • string
      Example:admin

Responses

200

Request accepted successfully

Decline request

put/v2024-07-01/access/{resourceType}/{resourceId}/requests/{requestId}/decline

Permissions sanity.{resourceType}.members.invite

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • requestIdstringrequired

    The ID of the request.

Responses

200

Request declined successfully

List all request for current user

get/v2024-07-01/access/requests/me

Requires an authenticated user.

Responses

200

A list of user Requests

Invites

Manage and accept invites.

Get current user's invites filtered by status/resource

get/v2025-07-11/access/invites/me

Retrieves a list of invites for the current user, using the email.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

Query parameters

  • statusarray

    Filter invites by status.

    items
    • itemsstring
  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

Responses

200

A paginated list of invites

  • dataarrayrequired
    Show child attributes
    items
    • idstringrequired
    • statusstringrequired
    • resourceTypestringrequired

      Resources are entities that can be managed and accessed through the Access API.

      Example:project
    • resourceIdstringrequired
    • rolestringrequired
    • emailstring

      The email address of the invitee. Only present if the invite is still pending.

    • inviterTypestringrequired
    • inviterIdstring

      The ID of the user or service that created the invite. Only present if the invite was created by a user.

    • inviteeIdstring

      The ID of the user that accepted the invite. Only present if the invite has been accepted.

    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

Get invites

get/v2025-07-11/access/{resourceType}/{resourceId}/invites

Retrieves a list of invites for the specified resource.

Only pending invites are retrieved by default. Use the optional status parameter to change the filter behavior. You can select multiple statuses by repeating the parameter.

Children invites

By default, only invites for the specified resource are returned. Use the optional includeChildren parameter to include invites for children resources as well. This only applies to organization resources.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.members.read

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Query parameters

  • statusarray

    Filter invites by status.

    items
    • itemsstring
  • includeChildrenboolean

    Whether to include children resources in the response. Only applies to organization resources.

    Example:false
  • nextCursorstring

    The cursor for pagination. Use the nextCursor from the previous response to get the next page.

  • limitintegerdefault: 100

    The number of items to return per page.

Responses

200

A paginated list of invites

  • dataarrayrequired
    Show child attributes
    items
    • idstringrequired
    • statusstringrequired
    • resourceTypestringrequired

      Resources are entities that can be managed and accessed through the Access API.

      Example:project
    • resourceIdstringrequired
    • rolestringrequired
    • emailstring

      The email address of the invitee. Only present if the invite is still pending.

    • inviterTypestringrequired
    • inviterIdstring

      The ID of the user or service that created the invite. Only present if the invite was created by a user.

    • inviteeIdstring

      The ID of the user that accepted the invite. Only present if the invite has been accepted.

    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
  • nextCursorstring | nullrequired

    Cursor to get the next page of results, null if there are no more results.

Create invite

post/v2025-07-11/access/{resourceType}/{resourceId}/invites

Creates an invite for the specified resource.

The invitee will receive an email with a link to accept the invite.

Each invitee can only receive one invite per resource and role. Attempting to create an invite using a non-existent role, or a role that cannot be granted to users will result in a Bad Request error.

Unavailable resources

If the underlying resource is unavailable then a Bad Request error will be returned. A common example of an unavailable resource is a project that is blocked or archived.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.members.invite

Additionally, only administrators can invite other administrators.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy

Request body application/json

Responses

201

Invite created.

  • idstringrequired
  • statusstringrequired
  • resourceTypestringrequired

    Resources are entities that can be managed and accessed through the Access API.

    Example:project
  • resourceIdstringrequired
  • rolestringrequired
  • emailstring

    The email address of the invitee. Only present if the invite is still pending.

  • inviterTypestringrequired
  • inviterIdstring

    The ID of the user or service that created the invite. Only present if the invite was created by a user.

  • inviteeIdstring

    The ID of the user that accepted the invite. Only present if the invite has been accepted.

  • createdAtstring (date-time)required
  • updatedAtstring (date-time)required

Revoke invite

delete/v2025-07-11/access/{resourceType}/{resourceId}/invites/{inviteId}

Revokes an invite.

Attempting to revoke an invite that has already been accepted or revoked will result in a Bad Request error.

Authorization

This endpoint requires an authenticated user session with the following permissions:

  • sanity.{resourceType}.members.invite

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • inviteIdstringrequired

    The invite's unique identifier.

Responses

204

Invite revoked.

Get invite

get/v2025-07-11/access/{resourceType}/{resourceId}/invites/token/{inviteToken}

Retrieves an invite using its token.

Authorization

This endpoint does not require authentication.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • inviteTokenstringrequired

    The public token for the invite. This token is shared with the invitee.

Responses

200

Invite found.

  • idstringrequired
  • statusstringrequired
  • resourceTypestringrequired

    Resources are entities that can be managed and accessed through the Access API.

    Example:project
  • resourceIdstringrequired
  • rolestringrequired
  • emailstring

    The email address of the invitee. Only present if the invite is still pending.

  • inviterTypestringrequired
  • inviterIdstring

    The ID of the user or service that created the invite. Only present if the invite was created by a user.

  • inviteeIdstring

    The ID of the user that accepted the invite. Only present if the invite has been accepted.

  • createdAtstring (date-time)required
  • updatedAtstring (date-time)required

Accept invite

post/v2025-07-11/access/{resourceType}/{resourceId}/invites/token/{inviteToken}/accept

Accepts an invite using its token.

Attempting to accept an invite that is already accepted or revoked will result in a Bad Request error.

Once the invite has been accepted, the user will have access to the resource with the role assigned as part of the invitation.

Access is propagated internally and may take a up to a few minutes to be fully available across all systems.

Unavailable resources

If the underlying resource is unavailable then a Bad Request error will be returned. A common example of an unavailable resource is a project that is blocked or archived.

Member quota

Some resources have a limit on the number of members. If accepting an invite would go over this limit, then a Payment Required error is returned.

Authorization

This endpoint requires an authenticated user session.

Path parameters

  • resourceTypestringrequired

    The resource type to scope the access requests to.

  • resourceIdstringrequired

    The resource ID to scope the access request to. Must be a valid ID for the resource type.

    Example:c7ja4siy
  • inviteTokenstringrequired

    The public token for the invite. This token is shared with the invitee.

Responses

204

Invite accepted.