Roles Reference

API endpoints for managing roles, grants, and permissions

Project endpoints

A list of endpoints for dealing with users, grants, and roles for individual projects.

List all user grants

GET /projects/${projectId}/grants

Request

curl --request GET 'https://api.sanity.io/vX/projects/${projectId}/grants' \
--header 'Authorization: Bearer ${Bearer token}'

Output

{
  "sanity.project": [
    {
      "grants": [
        {
          "name": "createSession",
          "params": {}
        },
        {
          "name": "delete",
          "params": {}
        },
        {
          "name": "deployStudio",
          "params": {}
        },
        {
          "name": "read",
          "params": {}
        },
        {
          "name": "update",
          "params": {}
        }
      ],
      "config": {}
    }
  ],
  // ... other grants
}

List all roles

GET /projects/${projectId}/roles

Input

curl --request GET 'https://api.sanity.io/vX/projects/${projectId}/roles' \
--header 'Authorization: Bearer ${Bearer Token}'

Response

[
  {
    "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(\"**\")"
          }
        }
      ]
      // ... additional grants
    }
  }
  // ... additional roles
]

List permission resources

GET /projects/${projectId}/permissionResourceSchemas

Request

curl --request GET 'https://api.sanity.io/vX/projects/${projectId}/permissionResourceSchemas' \
--header 'Authorization: Bearer ${Bearer Token}'

Output

[
  {
    "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": "View history for 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"
          }
        ]
      }
    ]
  }
]

List users with roles

GET /projects/${projectId}/acl

Request

curl --location --request GET 'https://api.sanity.io/vX/projects/${projectId}/acl' \
--header 'Authorization: Bearer ${Bearer Token}'

Output

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

Add user role

PUT /projects/${projectId}/acl/${userId}

Request

curl --location --request PUT 'https://api.sanity.io/vX/projects/${projectId}/acl/${userId}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "roleName": "${roleName}"
}'

Delete user role

DELETE /projects/${projectId}/acl/${userId}

Request

curl --request DELETE 'https://api.sanity.io/vX/projects/${projectId}/acl/${userId}' \
--header 'Authorization: Bearer ${Bearer Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "roleName": "${roleToRemove}"
}'

Organization endpoints

API endpoints allowing inspection and modifications of roles and users in an organization.

Get all members and their roles

GET /organizations/${organizationID}/acl

Request

curl -X GET /organizations/${organizationId}/acl

Response

[
  {
    "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}

Give an organization member a role

PUT /organizations/${organizationId}/acl/${sanityUserId}

Request

curl -X PUT /organizations/${organizationId}/acl/${sanityUserId} \
	--header "Content-Type: application/json" \
	--data '{roleName:"editor"}'

Response

HTTP 201 Created

Remove a role from an organization member

DELETE /organizations/${organizationId}/acl/${sanityUserId}

Request

curl -X DELETE /organizations/${organizationId}/acl/${sanityUserId} \
	--header "Content-Type: application/json" \
	--data '{roleName:"editor"}'

Response

HTTP 200 OK

Get all grants for current user

GET /organizations/${organizationId}/grants

Request

curl -X GET /organizations/${organizationId}/grants \

Dataset ACL

GET /projects/${projectId}/datasets/${datasetName}/acl

Request

curl -X GET https://api.sanity.io/v2021-06-07/projects/${projectId}/datasets/${datasetName}/acl

Response

[
	{
		"filter": "_id in path(\"**\")",
		"grants": ["read", "update", "create", "history"]
	}
]

Dataset grants

GET /projects/${projectId}/datasets/${datasetName}/grants

Request

curl -X GET https://api.sanity.io/v2021-06-07/projects/${projectId}/datasets/${datasetName}/grants

Output

{
  "sanity.document.filter.mode": [
    {
      "grants": [
        {
          "name": "mode",
          "params": {
            "mode": "publish",
            "history": true,
            "datasetPolicyName": "default"
          }
        }
      ],
      "config": {
        "filter": "_id in path(\"**\")"
      }
    }
  ]
}

Was this article helpful?