Install Jentic One Beta
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Roles, grants, and permissions HTTP Endpoints, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fsanity.io%2Fsanity-roles" | shStep 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fsanity.io%2Fsanity-roles" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
What an agent can do with Roles, grants, and permissions HTTP Endpoints API.
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
GET STARTED
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
Patterns agents use Roles, grants, and permissions HTTP Endpoints API for, with concrete tasks.
★ 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.
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.
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.
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.
Call PUT /auth/organizations/{organizationId}/providers/{providerId}/projects/{projectId}/role-mappings to map a SAML group rule to the editor role for project abc123
30 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.
METHOD
PATH
DESCRIPTION
/projects/{projectId}/acl
List project members and their roles
/projects/{projectId}/acl/{projectUserId}
Add roles to a project member
/projects/{projectId}/acl/{projectUserId}
Remove a role from a project member
/projects/{projectId}/roles
List all roles in a project
/projects/{projectId}/roles
Create a custom role
/projects/{projectId}/grants
Add grants to a custom role
/projects/{projectId}/permissionResources
Create a custom permission resource
/organizations/{organizationId}/acl
List organization members and roles
/projects/{projectId}/acl
List project members and their roles
/projects/{projectId}/acl/{projectUserId}
Add roles to a project member
/projects/{projectId}/acl/{projectUserId}
Remove a role from a project member
/projects/{projectId}/roles
List all roles in a project
/projects/{projectId}/roles
Create a custom role
/projects/{projectId}/grants
Add grants to a custom role
/projects/{projectId}/permissionResources
Create a custom permission resource
/organizations/{organizationId}/acl
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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.
Alternatives and complements available in the Jentic catalogue.
Specific to using Roles, grants, and permissions HTTP Endpoints API through Jentic.
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.
For 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.
Use for: List all members of my Sanity project and their roles, Give the editor role to this user in project abc123, I want to create a Translator role that can only edit translated documents, Check which grants my token has on the production dataset
Not supported: Does not manage projects, datasets, content, or user sign-in. Use for Sanity roles, grants, permission resources, and SSO role mappings only.
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.
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.
List organization members and roles
Base layer of spec validity and structural soundness.
Aggregated quality score from linter diagnostics, weighted by severity.
Percentage of `$ref` references that resolve successfully.
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
Structural correctness score based on schema issues using logarithmic dampening.
Clarity, completeness, and ingestion readiness for developers and tooling.
How richly the API is illustrated with examples.
Percentage of examples that conform to their schemas.
Percentage of operations with complete response definitions (success, client error, server error).
Health of API ingestion, bundling, and resolution within Jentic pipelines.
Semantic breadth, depth, and agent comprehension for AI systems.
Coverage of descriptions across API elements.
Coverage of RFC 9457 Problem Details for error responses.
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
Coverage of summaries across operations/tags/info.
Functional utility, complexity comfort, and AI orchestration readiness.
Agent comfort level based on API operational and structural complexity.
Trust, risk posture, and security compliance.
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
Findability, semantic richness, and reasoning readiness.
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>