Build a custom role with the Access API

How to build, assign, and verify custom Sanity roles via the Access API, with recipes for common scenarios.

This page covers the patterns you'll use to build, assign, and verify custom roles via the Access API. If you're new to roles, read the concepts page first.

You'll need:

• A Sanity project and a token that can call the Access API. An admin user token (from sanity login) works; a project- or organization-scoped robot token also works for most operations.
• Comfort making authenticated HTTP requests with curl or a similar client, and reading and writing JSON request bodies.

The examples on this page use API version v2026-07-11. Pin to a version that suits your project's needs.

Every recipe on this page relies on one pattern that surprises most authors the first time they see it. Read this section before you write any role JSON.

Both sanity.document.filter and sanity.document.filter.mode are GROQ-filter-backed types: they scope a permission to documents matching a config.filter predicate. They differ in how the action is expressed. For sanity.document.filter.mode, the outer action field is always the literal string "mode". The semantic action you actually care about (read, create, or publish) goes inside params.mode.

{
  "name": "all-docs",
  "action": "mode",
  "params": { "mode": "publish" }
}

This shape is what enables dataset and history scoping via additional params fields:

{
  "name": "all-docs",
  "action": "mode",
  "params": { "mode": "publish", "dataset": "staging" }
}

For permissions of type sanity.document.filter (the non-.mode variant) and for project-level types like sanity.project.datasets, the action field carries the semantic action directly: read, create, update. Available actions vary by type: project-level types like sanity.project.datasets also include delete, while sanity.document.filter has no delete action (its update grant covers delete). No params block needed.

{ "name": "sanity-project-datasets", "action": "read" }

When you read role JSON, ask yourself: is this a .mode permission? If yes, the action is "mode" and the real action is in params.mode. If no, the action is the action.

The recipes on this page use both. Pick based on what scoping you need:

• sanity.document.filter when a GROQ filter alone is enough to scope the permission. Best for simple type-matching filters (Recipe: Content-type-restricted editor: "edit articles only"), release-action filtering (Recipe: Release reviewer: "schedule but not publish"), and any case where you don't need dataset or history scoping.
• sanity.document.filter.mode when you need first-class params.dataset for dataset scoping (Recipes: Read-only analyst, Single-dataset editor), params.history for history scoping, or the canonical mode: "publish" shape for expressing publish authority (Recipe: Attribute-based editing).

If you're not sure, start from the closest recipe match above.

Avoid mixing them in the same role without understanding the dataset-bypass gotcha: the params.dataset scope on a sanity.document.filter.mode grant doesn't constrain sibling sanity.document.filter grants in the same role; those escape dataset scope and apply to all datasets. If you need dataset scoping, use sanity.document.filter.mode for all the document-plane permissions in that role.

Building a custom role follows four steps in order. The example below creates an "article-editor" role: a role that can update and create documents of type article, and read articles.

Custom permissions are scoped to a resource (organization or project) and addressed by their name. The name is the unique identifier within the resource scope.

curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "articles-only",
    "title": "Articles only",
    "description": "Only allow access to articles",
    "type": "sanity.document.filter",
    "config": { "filter": "_type == \"article\"" }
  }'

The type field references the predefined permission type that this custom permission specializes. The config.filter field holds a GROQ predicate that narrows the permission to documents matching the filter.

A role bundles permissions with two flags (appliesToUsers and appliesToRobots) controlling who the role can be assigned to.

curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "article-editor",
    "title": "Article editor",
    "description": "Can edit and manage articles; reads articles",
    "appliesToUsers": true,
    "appliesToRobots": false,
    "permissions": [
      { "name": "sanity-project",         "action": "read" },
      { "name": "sanity-project-members", "action": "read" },
      { "name": "sanity-project-roles",   "action": "read" },
      { "name": "articles-only",          "action": "update" },
      { "name": "articles-only",          "action": "create" },
      { "name": "articles-only",          "action": "read" }
    ]
  }'

The first three entries (sanity-project, sanity-project-members, sanity-project-roles) are predefined permissions that almost every role needs: the user has to be able to read basic project metadata for the API client to initialize. The last three entries grant update, create, and read actions on the custom articles-only permission you defined in Step 1. (Note that on sanity.document.filter, the update action allows both update and delete on matching documents; see two common traps when verifying denials.)

curl -X PUT "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/users/$SANITY_USER_ID/roles/article-editor" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

$SANITY_USER_ID is the target user's Sanity user ID (not their email). You can look it up with GET /v2026-07-11/access/project/$PROJECT_ID/users.

When you tear down a role, the API enforces one part of the cleanup order and silently rewrites the rest. Remove the assignments before deleting the role; clean up the permissions last to avoid silently degrading other roles.

# 1. Unassign the role from each user
curl -X DELETE "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/users/$SANITY_USER_ID/roles/article-editor" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 2. Delete the role
curl -X DELETE "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles/article-editor" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 3. Delete the custom permission (only after confirming no other roles depend on it; see warning below)
curl -X DELETE "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions/articles-only" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

• Required: Remove role assignments before deleting a role. The API rejects role deletion while the role is assigned to any user; the role needs to be removed from users first.
• Allowed but discouraged: The API permits permission deletion even when roles still reference the permission. When this happens, the API silently strips the dangling entries from each affected role's permissions[] array. No error and no notification; the activity log records the permission deletion itself, but not which roles lost grants. The role and its user assignments remain, but the role's effective permission set narrows.

Why this matters: if a role's only document-scoping grant comes from a custom permission that gets deleted, users assigned to that role can lose document-plane access without any explicit signal. The only way to detect it after the fact is to GET the role and compare its permissions[] array to what you expected.

Recommended teardown order:

• Remove the role's assignments from each user (required).
• Delete the role (now allowed; will reject if any assignment remains).
• Delete the custom permission only after confirming no other roles reference it. If other roles do reference it, decide whether to update those roles first (replace the reference) or accept the silent narrowing.

If you're deleting a permission as part of a refactor rather than a teardown (the permission stays in use but you're restructuring), follow the same step 3: update affected roles before deleting the permission.

After Step 3, confirm the role took effect by calling /user-permissions/me/check as the assigned user:

curl "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/user-permissions/me/check?permissions=sanity.document.filter.update&permissions=sanity.project.members.invite" \
  -H "Authorization: Bearer $USER_TOKEN"

{
  "data": {
    "sanity.document.filter.update": true,
    "sanity.project.members.invite": false
  }
}

For deeper testing patterns, including a CI integration sketch, see the verification section below.

Each recipe below follows the same shape: persona, mechanism, payloads, verification, caveats. Every recipe targets resourceType=project unless noted; adapt the resourceId and the URL path for organization-scoped roles.

Persona: A CI pipeline that deploys the Studio on every main-branch merge. It must not be able to mutate content or manage users.

Capabilities needed:

• sanity deploy (the Studio) needs sanity.project:deployStudio.
• sanity dataset copy (optional, for snapshot-based deploys) needs sanity.project.datasets:{read, create}.

Mechanism: Define a robot-only role (appliesToUsers: false, appliesToRobots: true) with only deploy-relevant permissions. Create a robot under the role and use its token for CI.

Anti-pattern to avoid: Assigning the built-in administrator role to a CI robot because it's faster to set up. Any pipeline compromise becomes a full project takeover, including members and tokens. Custom roles exist for exactly this reason.

Payloads:

# Step 1: Create the role (no custom permissions needed; all are predefined).
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "title": "CI/CD deploy",
    "description": "Minimum permissions for Studio deploy pipelines",
    "appliesToUsers": false,
    "appliesToRobots": true,
    "permissions": [
      { "name": "sanity-project",          "action": "deployStudio" },
      { "name": "sanity-project-datasets", "action": "read" },
      { "name": "sanity-project-datasets", "action": "create" }
    ]
  }'

# Step 2: Create a robot under this role.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/robots" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "GitHub Actions deploy",
    "memberships": [
      {
        "resourceType": "project",
        "resourceId": "'"$PROJECT_ID"'",
        "roleNames": ["ci-deploy"]
      }
    ]
  }'
# The response includes the robot's bearer token. Store it as a repository secret.
# To set an explicit token expiry (recommended for CI), include "expiresAt": "<ISO-8601 timestamp>".

Verification:

# Verify the robot's permissions directly with /user-permissions/me/check
# (robot tokens work fine on this endpoint), or attempt the gated action.
curl "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/user-permissions/me/check?permissions=sanity.project.deployStudio" \
  -H "Authorization: Bearer $ROBOT_TOKEN"
# Expected: { "data": { "sanity.project.deployStudio": true } }

Caveats:

• sanity deploy from the CLI authenticates with a user token. Set the SANITY_AUTH_TOKEN environment variable to override the user token.
• Granting create on sanity-project-datasets is broader than "copy into an existing dataset." If snapshotting isn't needed, drop it.

Persona: A content-team member who prepares releases and schedules go-live times, but requires a senior editor's approval before the actual publication.

Mechanism: Release actions decompose into permission checks against synthetic document IDs of the form _.releases.<releaseId>.actions.<action>. Granting update on a filter that matches a subset of these IDs authorizes specific release actions. Withhold the filter match for _.releases.*.actions.publish and the user can't publish. (The update action here authorizes release actions like schedule and unschedule; it does not interact with the data-plane document mutation gate where the "update grants delete" mechanic applies. See two common traps when verifying denials.)

Permissions granted: schedule, unschedule, edit, archive, unarchive. Permissions withheld: publish, delete.

Payloads:

# Step 1: Create the filter permission.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release-reviewer-scope",
    "title": "Release reviewer scope",
    "description": "Allows schedule, unschedule, edit, archive, and unarchive on releases; withholds publish and delete",
    "type": "sanity.document.filter",
    "config": {
      "filter": "_id in path(\"_.releases.*.actions.schedule\") || _id in path(\"_.releases.*.actions.unschedule\") || _id in path(\"_.releases.*.actions.edit\") || _id in path(\"_.releases.*.actions.archive\") || _id in path(\"_.releases.*.actions.unarchive\")"
    }
  }'

# Step 2: Create the role bundling release scoping with baseline read access.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release-reviewer",
    "title": "Release reviewer",
    "description": "Can schedule releases but not publish them",
    "appliesToUsers": true,
    "appliesToRobots": false,
    "permissions": [
      { "name": "sanity-project",         "action": "read" },
      { "name": "sanity-project-members", "action": "read" },
      { "name": "sanity-project-roles",   "action": "read" },
      { "name": "release-reviewer-scope", "action": "update" }
    ]
  }'

# Step 3: Assign to the user as in the four-step flow above.

Verification: This role is best validated end to end. Assign the role to a test user, then attempt both schedule and publish actions: schedule should succeed; publish should return a 403 from the release dry-run check.

Caveats:

• The filter string exposes synthetic document ID paths. These are stable today but may be replaced by a higher-level abstraction in a future release.
• This role grants only release-action authority. It doesn't include the document-editing permissions needed to change release contents. Combine it with an editor role if the reviewer should also edit release drafts.

Persona: A BI analyst who queries production data via the API from an external tool. The role must never mutate.

Mechanism: Grant read-only access on documents plus the minimum project metadata. Deny everything else by omission. The role applies to robots so the analyst's tool can use a scoped token.

Payloads:

# Step 1: Create the read-scope filter (optional; narrows read to the production dataset).
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analyst-read-scope",
    "title": "Analyst read scope",
    "description": "Read-only permission for analysts",
    "type": "sanity.document.filter.mode",
    "config": { "filter": "true" }
  }'

# Step 2: Create the role.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read-only-analyst",
    "title": "Read-only analyst",
    "description": "Query production data; no mutations",
    "appliesToUsers": true,
    "appliesToRobots": true,
    "permissions": [
      { "name": "sanity-project",          "action": "read" },
      { "name": "sanity-project-datasets", "action": "read" },
      {
        "name": "analyst-read-scope",
        "action": "mode",
        "params": { "mode": "read", "dataset": "production" }
      }
    ]
  }'

Verification:

# A query should succeed.
curl "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/query/production?query=*\[_type==%22article%22\]\[0...5\]" \
  -H "Authorization: Bearer $ROBOT_TOKEN"

# A mutation should return 403.
curl -X POST "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/mutate/production" \
  -H "Authorization: Bearer $ROBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mutations":[{"create":{"_type":"article","title":"nope"}}]}'
# Expected: 403 with an insufficient-permissions error.

Caveats:

• Most uses of @sanity/client need sanity.project:read to fetch project metadata. Pure GROQ queries with an explicit dataset don't need it, but most other operations do; if you omit the grant, some operations will return a misleading error.
• The Content Lake POST /actions endpoint is a mutation surface; read-only roles will (correctly) return 403 there. Some teams conflate "doesn't mutate" with "can call any endpoint that returns data," so be explicit when documenting the role for your stakeholders.
• If the analyst needs to enumerate all datasets (not only production), drop the params.dataset scoping.

Persona: A content contributor who edits in staging but must never touch production.

Mechanism: Native params.dataset scoping. The sanity.document.filter.mode permission's params.dataset field is first-class. The Access API gates the grant to that dataset without filter-string escape hatches.

Payloads:

# Step 1: Create an unscoped filter permission (the "everything" filter).
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "all-docs",
    "title": "All documents",
    "description": "Access all documents",
    "type": "sanity.document.filter.mode",
    "config": { "filter": "true" }
  }'

# Step 2: Role granting publish-mode scoped to the staging dataset.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging-editor",
    "title": "Staging editor",
    "description": "Full editing rights in staging dataset only",
    "appliesToUsers": true,
    "appliesToRobots": false,
    "permissions": [
      { "name": "sanity-project",          "action": "read" },
      { "name": "sanity-project-members",  "action": "read" },
      { "name": "sanity-project-roles",    "action": "read" },
      { "name": "sanity-project-datasets", "action": "read" },
      {
        "name": "all-docs",
        "action": "mode",
        "params": { "mode": "publish", "dataset": "staging" }
      }
    ]
  }'

Verification:

# Staging mutation succeeds.
curl -X POST "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/mutate/staging" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mutations":[{"create":{"_type":"article","title":"test"}}]}'

# Production mutation returns 403.
curl -X POST "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/mutate/production" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mutations":[{"create":{"_type":"article","title":"nope"}}]}'

Caveats:

• The all-docs permission can be reused across many roles; it's a packaging of "filter = true." Consider naming it all-docs-filter if you'll stack it into other recipes.
• If you scope to a dataset that doesn't exist yet, the grant is inert but valid. Create the dataset first.

Persona: A marketing editor who should edit and manage article documents only, not product or config.

Mechanism: sanity.document.filter with a type-matching filter, granted at update and create actions. Reads are scoped to articles by the same filter: deny-by-omission means the role reads articles only. See the caveat about reference integrity below.

Payloads:

# Step 1: Article-only filter.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "articles-only",
    "title": "Articles only",
    "description": "Access articles only",
    "type": "sanity.document.filter",
    "config": { "filter": "_type == \"article\"" }
  }'

# Step 2: Role with update and create on articles, read on everything.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "article-editor",
    "title": "Article editor",
    "description": "Edits and manages articles only; reads references to other types",
    "appliesToUsers": true,
    "appliesToRobots": false,
    "permissions": [
      { "name": "sanity-project",         "action": "read" },
      { "name": "sanity-project-members", "action": "read" },
      { "name": "sanity-project-roles",   "action": "read" },
      { "name": "articles-only",          "action": "update" },
      { "name": "articles-only",          "action": "create" },
      { "name": "articles-only",          "action": "read"   }
    ]
  }'

Verification:

# Creating an article succeeds.
curl -X POST "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/mutate/production" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mutations":[{"create":{"_type":"article","title":"ok"}}]}'

# Creating a product returns 403.
curl -X POST "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/mutate/production" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mutations":[{"create":{"_type":"product","sku":"nope"}}]}'

Caveats:

• Reference leakage. An article can point to a product via a reference field. Because reads are scoped to articles, the editor can't see products in the reference picker. Consider situations like this when creating narrow permissions.
• After a permission change, the Studio's permission cache may briefly show the pre-role state. Buttons might appear available even though the action will return 403 at submit time. Ask the user to reload after a role change.
• The update grant covers delete. Granting update on articles-only allows the editor to delete matching article documents at the data-mutate gate, in addition to updating them. Filter scope is enforced (non-article documents remain protected), but if your intent was edit-only, gate deletion higher up in your application. See two common traps when verifying denials.

Persona: An editor who can edit only documents where they're listed in an assignees array.

Mechanism: sanity.document.filter.mode with a user-attribute template. The filter resolves at request time using the calling user's identity or stored attributes. For the simple "is the caller listed in this document's assignees?" pattern, use identity() directly.

Payloads:

# Step 1: Filter based on identity().
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/permissions" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "assignee-editor-filter",
    "title": "Documents I am assigned to",
    "description": "User-assigned document access",
    "type": "sanity.document.filter.mode",
    "config": {
      "filter": "identity() in assignees[]._ref"
    }
  }'

# Step 2: Role.
curl -X POST "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "assignee-editor",
    "title": "Assignee editor",
    "description": "Edit documents where the user is in the assignees array",
    "appliesToUsers": true,
    "appliesToRobots": false,
    "permissions": [
      { "name": "sanity-project",         "action": "read" },
      { "name": "sanity-project-members", "action": "read" },
      { "name": "sanity-project-roles",   "action": "read" },
      {
        "name": "assignee-editor-filter",
        "action": "mode",
        "params": { "mode": "publish" }
      }
    ]
  }'

For attribute-based variants (for example, team membership set admin-side), reference user::attributes() in the filter:

"config": {
  "filter": "team == user::attributes().teamId"
}

At request time, user::attributes().teamId resolves to the calling user's stored teamId attribute.

Verification: Filters are evaluated per document per caller, so verification is easiest as the affected user:

curl "https://$PROJECT_ID.api.sanity.io/v2026-07-11/data/query/production?query=*\[_type==%22article%22\]" \
  -H "Authorization: Bearer $USER_TOKEN"
# Returns only articles where the user is in assignees.

Caveats:

• Filters must be simple. No joins, no subqueries, no custom functions. A filter like *[_type == "user" && _id == identity()].assignedDocs[]._ref is rejected at permission-create time. Denormalize the data (put the assignee list in the article document itself) or gate the feature higher up in your application.
• Attribute propagation: User-attribute changes push to the permission layer immediately on write, typically landing within a second; a polling fallback catches any missed updates within roughly 10-30 seconds.
• identity() is the user's Sanity user ID, not an email or profile ID. When you denormalize, store the sanityUserId value.
• The mode grant covers delete on matching documents. mode on sanity.document.filter.mode grants delete capability for documents matching the filter (the same data-mutate gate semantics as update on sanity.document.filter; see two common traps when verifying denials). Behavior on documents that do NOT match the filter is not currently documented as a contract; for security-critical denials on this recipe, verify end to end against documents your role both should and should not match.

After you've assigned a role, two patterns are useful for verification.

/user-permissions/me/check reads from the authoritative permission store, so it's consistent within milliseconds of a role edit.

curl "https://api.sanity.io/v2026-07-11/access/project/$PROJECT_ID/user-permissions/me/check?permissions=sanity.document.filter.update&permissions=sanity.project.datasets.create" \
  -H "Authorization: Bearer $USER_TOKEN"

{
  "data": {
    "sanity.document.filter.update": true,
    "sanity.project.datasets.create": false
  }
}

Each permissions query parameter is a dot-delimited <type>.<action> string. The endpoint checks the coarse (resource, action) pair only; it doesn't evaluate params.mode or params.dataset. For mode-scoped or dataset-scoped permissions, supplement the check with a real action against a test environment.

For end-to-end validation in CI, set up a known test user, assign the role, run permission checks plus real actions, and tear down.

import {createClient} from '@sanity/client'

const admin = createClient({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'YOUR_DATASET_NAME',
  token: 'ADMIN_TOKEN',
  apiVersion: '2026-07-11',
  useCdn: false,
})

const testUser = createClient({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'YOUR_DATASET_NAME',
  token: 'TEST_USER_TOKEN',
  apiVersion: '2026-07-11',
  useCdn: false,
})

beforeAll(async () => {
  await admin.request({method: 'POST', uri: `/access/project/${PROJECT_ID}/permissions`, body: {/* permission */}})
  await admin.request({method: 'POST', uri: `/access/project/${PROJECT_ID}/roles`, body: {/* role */}})
  await admin.request({method: 'PUT',  uri: `/access/project/${PROJECT_ID}/users/${SANITY_USER_ID}/roles/article-editor`})
})

afterAll(async () => {
  await admin.request({method: 'DELETE', uri: `/access/project/${PROJECT_ID}/users/${SANITY_USER_ID}/roles/article-editor`})
  await admin.request({method: 'DELETE', uri: `/access/project/${PROJECT_ID}/roles/article-editor`})
  await admin.request({method: 'DELETE', uri: `/access/project/${PROJECT_ID}/permissions/articles-only`})
})

test('article-editor can update articles but not products', async () => {
  const res = await testUser.request({
    method: 'GET',
    uri: `/access/project/${PROJECT_ID}/user-permissions/me/check?permissions=sanity.document.filter.update`,
  })
  expect(res.data['sanity.document.filter.update']).toBe(true)

  // Mutations are gated at request time by the Content Lake.
  await expect(testUser.create({_type: 'product', sku: 'nope'})).rejects.toThrow(/403|insufficient/i)
})

Note on robot tokens: The /user-permissions/me/check endpoint accepts robot tokens, so a robot can verify its own granted permissions directly with the same query pattern shown above. (/users/me is the one /me endpoint that requires a user session, but the permission-check path doesn't.)

Re-verify after permission changes. If a custom permission referenced by this role has been deleted, the role's permissions[] array is silently rewritten (see Cleanup behavior above). After any permission deletion, re-fetch any role that referenced it and confirm its permissions[] matches your expectations.

Note on role propagation. Role and permission changes propagate to the Content Lake mutation gate asynchronously: the role API records the change immediately, then rebuilds the affected dataset ACLs and pushes them to the Content Lake, which applies them in real time as they arrive. A single change typically lands within seconds; under churn (many roles created or modified in close succession), the throttled rebuild step can take noticeably longer. The /access/... endpoints answer from the authoritative store and aren't affected. For CI pipelines that create roles and immediately attempt mutations, build in a retry window.

When a custom role is supposed to deny an action, the cleanest test is to attempt the action and observe a 403. Two traps can make a denial look like it works when it doesn't.

Confirm the identity you're testing as. If the test identity is also a member of another role that grants the action (for example, an administrator account in the same project), the action will succeed and the denial test silently passes. Before concluding a denial works, call /user-permissions/me/check with the test identity's token and confirm the relevant (type, action) returns false. The check returns the authoritative grant set for whatever identity the token represents, so a false there guarantees no other role on that identity is granting the action.

update on sanity.document.filter grants delete capability. On sanity.document.filter permissions, granting update allows both update and delete mutations at the data-mutate gate. There's no separate delete action on this permission type, and no update-without-delete grant available. A role with {name: <filter-perm>, action: update} can delete documents matching the filter, even though the role body contains no delete entry. To deny deletion while allowing edits, gate deletion at a different layer (a workflow tool, a higher-tier role required for destructive actions, or a server-side check before the mutation hits the Content Lake).

These traps share a shape: a role looks restrictive on paper, but the actual capability surface is broader than the role body suggests. When designing a custom role for a security-sensitive surface, verify denials with a real action attempt against a known-isolated test identity, rather than by reading the role body alone.

This section maps user-visible capabilities to the Access API permissions you'd grant in a custom role to enable or restrict each capability.

The tables answer the question: "I want a custom role that can do X. Which permission do I grant?"

These permissions gate the surfaces where users edit content: creating, publishing, deleting, discarding, and duplicating documents, plus the read-only banner on the form itself.

Patterns seen in the wild:

• Edit but not publish: Grant mode: "create" but not mode: "publish". This is exactly how the built-in contributor role is composed.
• Type-restricted editor: Grant update and create with a filter like _type == "article".
• Dataset-scoped editor: Grant mode: "publish" with params.dataset: "staging".

Releases are bundles of versioned documents that publish atomically. Each release action (create, publish, schedule, archive, edit metadata) is gated by a grant on a synthetic document ID of the form _.releases.<releaseId>.actions.<action>. You grant sanity.document.filter:update with a filter that matches the action IDs you want to authorize.

Two capabilities live at the project-management level rather than the document plane.

The full request-access flow is pinned to v2024-07-01 and covers five endpoints. See the Access API HTTP reference for the complete request schemas.

Custom roles can't express everything. If you're trying to build a role and the filter mechanism rejects your design, three patterns usually cover the gap:

• Denormalize the data. If your filter needs to follow a reference (for example, looking up a user document to read its assignedDocs array), copy the data you're filtering on into the document itself. Filters can read fields on the document being checked; they can't follow references to other documents.
• Gate higher up. If the access rule requires logic the filter system can't express (subqueries, custom functions, complex branching), enforce it in your application layer or a webhook rather than in the role.
• Test in a non-production environment first. Assign the role to a test user account in a staging dataset (or a separate test project) and attempt the actions you expect to allow and deny before rolling out to production users.

The concepts page lists the full set of capabilities you can and can't express in custom roles today.