canonical: https://jentic.com/apis/sanity.io/sanity-roles

# Sanity Roles, grants, and permissions HTTP Endpoints

The Sanity Roles API controls who can do what in Sanity projects and organizations: it lists members and their roles, assigns or removes roles, and defines custom roles with their own grants. Grants pair a permission such as read or update with a permission resource, and custom permission resources of type sanity.document.filter use a GROQ filter to limit access to matching documents. It also reports the current user's grants at organization, project, and dataset level, and maps SAML SSO groups to project roles. Missing permissions return 401 with the code missing_grant rather than 403.

## For AI agents

List who holds which role in a Sanity project or organization, assign or remove roles, and build custom roles from grants on permission resources such as GROQ document filters.

## Scope

Does not manage projects, datasets, content, or user sign-in. Use for Sanity roles, grants, permission resources, and SSO role mappings only.

## Capabilities

- List the users and robots in a Sanity project with their roles, optionally filtered by the roles[] query parameter
- Add one or several roles to a project member with roleName or roleNames, optionally replacing their other roles with deleteExistingRoles
- Create custom project roles with a name, title, and appliesToUsers or appliesToRobots flags
- Attach or remove grants on custom roles by permissionName and permissionResourceId or permissionResourceName
- Define custom permission resources such as a sanity.document.filter with a GROQ filter in its config
- Read the current user's grants for an organization, a project, or a single dataset, and a dataset's access control list
- Create, update, or delete SAML SSO role mappings for a project under an organization's identity provider

## Use cases

### AI agent running access reviews

An agent asked to audit who can publish content in a Sanity project searches Jentic for 'list Sanity project members and roles', loads the listProjectRoleAssignments operation, and filters with roles[] to find every holder of a given role. It then calls listProjectMemberGrants for each member to see the project-level grants they actually carry, and reports the result without the token ever entering its context.

Example prompt: Call GET `/projects/{projectId}/acl` for project abc123 with roles[]=administrator, then GET `/projects/{projectId}/grants/{projectUserId}` for each returned member and summarize their grants

### Custom role for translators

A localization team needs editors who can only touch translated documents. The Roles API supports this in three steps: create a sanity.document.filter permission resource whose config.filter is a GROQ filter matching translated documents, create a custom role such as Translator, then add a grant that gives the role a permission on that resource. Custom roles and resources require the project's advancedRolesManagement feature.

Example prompt: POST `/projects/{projectId}/permissionResources` with permissionResourceType sanity.document.filter, a title, and config.filter, then POST `/projects/{projectId}/roles` with name translator and title Translator, then POST `/projects/{projectId}/grants` with roleName translator, a permissionName, and the new permissionResourceId

### Onboarding and offboarding project members

When someone joins or leaves a team, their Sanity roles have to change with them. The addRoleAssignment operation gives a member one role or several, and deleteExistingRoles swaps out everything else in the same call. The deleteRoleAssignment operation removes one role by roleName, or all roles when roleName is omitted, which removes the user from the project and ends their sessions. A project must keep at least one administrator.

Example prompt: Call PUT `/projects/{projectId}/acl/{projectUserId}` for project abc123 and user p1a2b3 with roleName editor and deleteExistingRoles true

### SAML SSO group-to-role mapping

Organizations that sign in through SAML SSO can map identity provider groups to Sanity project roles. The updateRoleMappings operation creates, updates, or deletes mappings for one project under one provider, changing only the mappings it names, and deleteRoleMappings clears every mapping for that provider and project, including the fallback mapping.

Example prompt: Call PUT `/auth/organizations/{organizationId}/providers/{providerId}/projects/{projectId}/role-mappings` to map a SAML group rule to the editor role for project abc123

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects/{projectId}/acl` | List project members and their roles |
| PUT | `/projects/{projectId}/acl/{projectUserId}` | Add roles to a project member |
| DELETE | `/projects/{projectId}/acl/{projectUserId}` | Remove a role from a project member |
| GET | `/projects/{projectId}/roles` | List all roles in a project |
| POST | `/projects/{projectId}/roles` | Create a custom role |
| POST | `/projects/{projectId}/grants` | Add grants to a custom role |
| POST | `/projects/{projectId}/permissionResources` | Create a custom permission resource |
| GET | `/organizations/{organizationId}/acl` | List organization members and roles |

## Key resources

- **Role assignments** — Which roles each project member, robot, or organization member holds
- **Roles** — Built-in and custom roles, with appliesToUsers and appliesToRobots flags
- **Grants** — A permission on a permission resource, attached to a custom role
- **Permission resources** — Things permissions apply to, such as sanity.project.members or a GROQ document filter
- **Role mappings** — SAML SSO group rules mapped to project roles

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 70 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 56 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 88 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-roles/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Roles API by hand means templating the apiVersion into the host, sending a bearer token, and decoding 401 missing_grant and 422 errors from a permission model of roles, grants, and resources. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Sanity puts the project id in the URL path (`/projects/{projectId}/...`), so a rule can pin your agent to one project and the operations you pick. You choose the operations it may call, so destructive ones like deleteRole or deletePermissionResource are not included unless you add them.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a role to a Sanity user' or 'list Sanity project roles', and Jentic returns the matching operation, such as addRoleAssignment or listRoles, with its input schema.

## Related APIs

- **Sanity Projects API** — Manage the Sanity projects, members, and invites these roles apply to
- **Sanity HTTP API** — Query and mutate the content that roles and grants protect
- **Auth0 Management API** — Manage users, roles, and permissions for your own application
- **Okta API** — Identity provider whose groups can feed SAML SSO role mappings

## FAQ

### What authentication does the Sanity Roles API use?

Per its OpenAPI spec, the Sanity Roles API uses a bearer token, either a Sanity API token or a user token, in the Authorization header. Each operation also needs a matching permission, for example read on sanity.project.members to list members, and a missing one returns 401 with code missing_grant. The dataset ACL operation also works without a token and then returns only the public view. Through Jentic the token is stored by your own instance and attached at call time.

### Can I create custom roles with the Sanity Roles API?

Yes. The createRole operation adds a custom role with a name and title, and you then attach grants through the project grants endpoint. Built-in roles cannot be updated or deleted, a role still assigned to users or robots cannot be deleted, and custom roles need the project's advancedRolesManagement feature.

### How do I restrict a Sanity role to certain documents?

Create a permission resource with permissionResourceType set to sanity.document.filter and a GROQ filter in config.filter, then add a grant on that resource to a custom role. The filter cannot be empty or contain a full query. The listPermissionResourceSchemas operation shows which resource types and permissions are available.

### What are the rate limits for the Sanity Roles API?

The OpenAPI spec does not specify rate limits. Check the Sanity documentation at https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity MCP server?

You don't need an MCP server to give your agent the Sanity Roles API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the role and grant operations it needs without loading a separate server's tool definitions.

### How do I list Sanity project members through Jentic?

Search Jentic for 'list Sanity project members and roles', load the listProjectRoleAssignments operation, and execute GET `/projects/{projectId}/acl` with your project id, adding roles[] to narrow the list. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Roles API?

Yes. A rule that allows only the GET operations under `/projects/abc123` lets the agent run access reviews on that one project, reading members, roles, and grants, while role assignment and role deletion stay off its list. Every call it makes is logged.
