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.
- Administrator or equal access is required to interact with this API.
Base API server URL
Sanity API base URL
https://api.sanity.io/{apiVersion}Variables
- apiVersionstringdefault:
"v2021-10-04"API version
Project
Endpoints for managing project-level roles and permissions
Path parameters
- projectIdstring
The ID of the project
Responses
List of users and their roles
- projectUserIdstring
The project user ID
Example:p..... - rolesarrayExample
[{"name":"administrator","title":"Administrator"}]Show child attributes
items
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
- isRobotboolean
Whether the user is a robot
Example:false
items
application/json[
{
"projectUserId": "p.....",
"roles": [
{
"name": "administrator",
"title": "Administrator"
}
],
"isRobot": false
}
]Responses
User role information
- rolestring
The role name
Example:administrator - projectUserIdstring
The project user ID
Example:p..... - isRobotboolean
Whether the user is a robot
Example:false
application/json{
"role": "administrator",
"projectUserId": "p.....",
"isRobot": false
}Delete a role from a user
/projects/{projectId}/acl/{userId}Remove a role from a user in a project
Path parameters
- projectIdstring
The ID of the project
Responses
List of user grants
- object
application/json{
"sanity.project": [
{
"grants": [
{
"name": "createSession",
"params": {}
},
{
"name": "delete",
"params": {}
},
{
"name": "deployStudio",
"params": {}
},
{
"name": "read",
"params": {}
},
{
"name": "update",
"params": {}
}
],
"config": {}
}
]
}Create a grant
/projects/{projectId}/grantsCreate a grant for in a project. Supply an ID from a permission resource to create a grant linked to that resource. This grant can then be assigned to a user.
Path parameters
- projectIdstring
The ID of the project
Request body application/json
- roleNamestring
- permissionNamestring
- permissionResourceIdstring
Responses
Path parameters
- projectIdstring
The ID of the project
Responses
List of roles
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
items
application/json[
{
"name": "administrator",
"title": "Administrator",
"description": "Administrate projects",
"isCustom": false,
"projectId": "3do82whm",
"grants": {
"sanity.document.filter.mode": [
{
"grants": [
{
"name": "mode",
"params": {
"mode": "publish",
"history": true,
"datasetPolicyName": "default"
}
}
],
"config": {
"filter": "_id in path(\"**\")"
}
}
]
}
}
]Path parameters
- projectIdstring
The ID of the project
Request body application/json
- titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - appliesToUsersboolean
Whether the role applies to users
Example:true - appliesToRobotsboolean
Whether the role applies to robots
Example:false
application/json{
"title": "Administrator",
"description": "Administrate projects",
"appliesToUsers": true,
"appliesToRobots": false
}Responses
Role created successfully
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
application/json{
"name": "administrator",
"title": "Administrator",
"description": "Administrate projects",
"isCustom": true,
"projectId": "3do82whm"
}List permission resources
/projects/{projectId}/permissionResourceSchemasList all permission resources in a project
Path parameters
The ID of the project
Responses
List of permission resources
- idstring
The ID of the permission resource
Example:srp-2ve36erw - titlestring
The title of the permission resource
Example:Sanity Document Filter - descriptionstring
The description of the permission resource
Example:Defines a permission resource for a filtered collection of Sanity documents - namestring
The name of the permission resource
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:update - titlestring
The title of the permission
Example:Update - descriptionstring
The description of the permission
Example:Update documents matching the filter - paramsarray
Show child attributes
items
- namestring
The name of the parameter
Example:datasetPolicyName - typestring
The type of the parameter
Example:string - titlestring
The title of the parameter
Example:Dataset Policy Name - descriptionstring
The description of the parameter
Example:A dataset policy name to scope the permission - defaultValuestring
The default value of the parameter
Example:default
items
application/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": "update",
"title": "Update",
"description": "Update documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name",
"description": "A dataset policy name to scope the permission",
"defaultValue": "default"
}
]
},
{
"name": "read",
"title": "Read",
"description": "Read documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name",
"description": "A dataset policy name to scope the permission",
"defaultValue": "default"
}
]
},
{
"name": "manage",
"title": "Manage",
"description": "Manage documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name",
"description": "A dataset policy name to scope the permission",
"defaultValue": "default"
}
]
},
{
"name": "history",
"title": "History",
"description": "Read the history of documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name",
"description": "A dataset policy name to scope the permission",
"defaultValue": "default"
}
]
},
{
"name": "editHistory",
"title": "Edit History",
"description": "Edit the history of documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name",
"description": "A dataset policy name to scope the permission",
"defaultValue": "default"
}
]
},
{
"name": "create",
"title": "Create",
"description": "Create documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name",
"description": "A dataset policy name to scope the permission",
"defaultValue": "default"
}
]
}
]
}
]Create a permission resource schema
/projects/{projectId}/permissionResourceSchemasCreate a permission resource schema in a project. Permission resources define what types of documents a user can interact with.
Path parameters
- projectIdstring
The ID of the project
Request body application/json
- idstring
The ID of the permission resource
Example:srp-2ve36erw - titlestring
The title of the permission resource
Example:Sanity Document Filter - descriptionstring
The description of the permission resource
Example:Defines a permission resource for a filtered collection of Sanity documents - namestring
The name of the permission resource
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:update - titlestring
The title of the permission
Example:Update - descriptionstring
The description of the permission
Example:Update documents matching the filter - paramsarray
Show child attributes
items
- namestring
The name of the parameter
Example:datasetPolicyName - typestring
The type of the parameter
Example:string - titlestring
The title of the parameter
Example:Dataset Policy Name - descriptionstring
The description of the parameter
Example:A dataset policy name to scope the permission - defaultValuestring
The default value of the parameter
Example:default
application/json{
"name": "sanity.document.filter",
"title": "Sanity Document Filter",
"description": "Defines a permission resource for a filtered collection of Sanity documents",
"config": [
{
"name": "filter",
"type": "string",
"title": "Filter",
"description": "GROQ filter limiting the document collection"
}
]
}Responses
Permission resource schema created successfully
- idstring
The ID of the permission resource
Example:srp-2ve36erw - titlestring
The title of the permission resource
Example:Sanity Document Filter - descriptionstring
The description of the permission resource
Example:Defines a permission resource for a filtered collection of Sanity documents - namestring
The name of the permission resource
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:update - titlestring
The title of the permission
Example:Update - descriptionstring
The description of the permission
Example:Update documents matching the filter - paramsarray
Show child attributes
items
- namestring
The name of the parameter
Example:datasetPolicyName - typestring
The type of the parameter
Example:string - titlestring
The title of the parameter
Example:Dataset Policy Name - descriptionstring
The description of the parameter
Example:A dataset policy name to scope the permission - defaultValuestring
The default value of the parameter
Example:default
application/json{
"name": "sanity.document.filter",
"title": "Sanity Document Filter",
"id": "srp-2ve36erw",
"config": [
{
"name": "filter",
"type": "string",
"title": "Filter",
"description": "GROQ filter limiting the document collection"
}
],
"permissions": [
{
"name": "update",
"title": "Update",
"description": "Update documents matching the filter",
"params": [
{
"name": "datasetPolicyName",
"type": "string",
"title": "Dataset Policy Name"
}
]
}
]
}Path parameters
The ID of the project
The name of the role
Responses
OK
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
application/json{
"name": "administrator",
"title": "Administrator",
"description": "Administrate projects",
"isCustom": false,
"projectId": "3do82whm",
"grants": {
"sanity.document.filter.mode": [
{
"grants": [
{
"name": "mode",
"params": {
"mode": "publish",
"history": true,
"datasetPolicyName": "default"
}
}
],
"config": {
"filter": "_id in path(\"**\")"
}
}
]
}
}Path parameters
The ID of the project
The name of the role
Request body application/json
- titlestring
The title of the role
Example:Administrator - descriptionstring
The description of the role
Example:Administrate projects - appliesToUsersboolean
Whether the role applies to users
Example:true - appliesToRobotsboolean
Whether the role applies to robots
Example:false
Responses
OK
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
application/json{
"name": "administrator",
"title": "Administrator",
"description": "Administrate projects",
"isCustom": false,
"projectId": "3do82whm",
"grants": {
"sanity.document.filter.mode": [
{
"grants": [
{
"name": "mode",
"params": {
"mode": "publish",
"history": true,
"datasetPolicyName": "default"
}
}
],
"config": {
"filter": "_id in path(\"**\")"
}
}
]
}
}Organization
Endpoints for managing organization-level roles and permissions
List organization members
/organizations/{organizationId}/aclGet a list of all members and their roles in an organization
Path parameters
- organizationIdstring
The ID of the organization
Responses
List of organization members and their roles
- sanityUserIdstring
The Sanity user ID
Example:g... - rolesarrayExample
[{"name":"administrator","title":"Administrator"}]Show child attributes
items
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
items
application/json[
{
"sanityUserId": "g...",
"roles": [
{
"name": "administrator",
"title": "Administrator"
}
]
},
{
"sanityUserId": "g...",
"roles": [
{
"name": "administrator",
"title": "Administrator"
}
]
}
]Get the roles of a single organization member
/organizations/{organizationId}/acl/{sanityUserId}Get the roles of a specific member in an organization
Path parameters
- organizationIdstring
The ID of the organization
- sanityUserIdstring
The Sanity user ID
Responses
Member roles information
- sanityUserIdstring
The Sanity user ID
Example:g... - rolesarrayExample
[{"name":"administrator","title":"Administrator"}]Show child attributes
items
- namestring
The role name
Example:administrator - titlestring
The role title
Example:Administrator - descriptionstring
A description of the role's permissions
Example:Administrate projects - isCustomboolean
Whether this is a custom role
Example:false - projectIdstring
The ID of the project this role belongs to
Example:3do82whm - grantsobject
The grants associated with this role
Give an organization member a role
/organizations/{organizationId}/acl/{sanityUserId}Add a role to a member in an organization
Path parameters
- organizationIdstring
The ID of the organization
- sanityUserIdstring
The Sanity user ID
Request body application/json
- roleNamestring
The name of the role to assign
Example:editor
application/json{
"roleName": "editor"
}Responses
Role added successfully
Remove a role from an organization member
/organizations/{organizationId}/acl/{sanityUserId}Remove a role from a member in an organization
Path parameters
- organizationIdstring
The ID of the organization
- sanityUserIdstring
The Sanity user ID
Request body application/json
- roleNamestring
The name of the role to assign
Example:editor
Responses
Role removed successfully
Get all grants for current user
/organizations/{organizationId}/grantsGet all grants for the current user in an organization
Path parameters
- organizationIdstring
The ID of the organization
Create/update project role mappings
/organizations/{organizationId}/providers/{providerId}/projects/{projectId}/role-mappingsCreate or update project role mappings for SAML SSO.
Robot Tokens
This endpoint cannot be accessed using robot tokens.
Authorization
Requires the update permission for the sanity.organization resource.
Path parameters
- organizationIdstring
The ID of the organization
- providerIdstring
The ID of the SSO provider
- projectIdstring
The ID of the project
Request body application/json
- fallbackRoleNamestring
The fallback role name (optional)
Example:viewer - roleMappingsarray
application/json{
"fallbackRoleName": "viewer",
"roleMappings": [
{
"id": "mapping-123",
"roleName": "editor",
"groupRule": ".*-admin"
}
]
}Responses
Role mappings created/updated successfully
Delete project role mappings
/organizations/{organizationId}/providers/{providerId}/projects/{projectId}/role-mappingsDeletes all project role mappings for a specific SSO provider and project within an organization. For use with SAML SSO implementations.
Authorization
Requires the update permission for the sanity.organization resource.
Path parameters
- organizationIdstring
The ID of the organization
- providerIdstring
The ID of the SSO provider
- projectIdstring
The ID of the project
Responses
Role mappings deleted successfully
Dataset
Endpoints for managing dataset-level access control and grants
Get dataset ACL
/projects/{projectId}/datasets/{datasetName}/aclGet the access control list for a dataset
Path parameters
- projectIdstring
The ID of the project
- datasetNamestring
The name of the dataset
Responses
Dataset ACL information
Get dataset grants
/projects/{projectId}/datasets/{datasetName}/grantsGet all grants for a dataset
Path parameters
- projectIdstring
The ID of the project
- datasetNamestring
The name of the dataset
Responses
Dataset grants information
application/json{
"sanity.document.filter.mode": [
{
"grants": [
{
"name": "mode",
"params": {
"mode": "publish",
"history": true,
"datasetPolicyName": "default"
}
}
],
"config": {
"filter": "_id in path(\"**\")"
}
}
]
}