openapi: 3.0.0 info: title: Sanity Access API description: >

A centralized API to manage resource access control through roles and permissions.

Overview:

Throughout this document the terms {resourceType} and {resourceId} refer to the resource the API request is being applied to.

{resourceType} can be an organization or project.
{resourceId} is the ID of the resource the API request affects.

When a client uses this API, it acts in the context of a specific resource. For example:

https://api.sanity.io/vX/access/organization/or0Bc1hcJ/roles
https://api.sanity.io/vX/access/project/c7ja4siy/roles

Key Concepts

Resource

A resource is an entity that can be managed and accessed through the API. Currently, the supported resources are organization and project.

Permission

Every resource has a list of permissions. These permissions represent actions that can be performed on the resource. A user or robot must be granted a permission (through a role) in order to perform the action.
The permission typically takes the form of {company}.{resourceType}.{objectName}.{action} but this is not always the case due to legacy terms.
There are both pre-defined and custom permissions. Pre-defined permissions are included with the product and are not editable.

Role

A role is a named collection of permissions that can be applied to a user or robot. Roles are in the scope of a resource and can only receive permissions that are in the same resource scope. For example, a project role can only include document permissions for that project.
A role is specific to a single resource and can only include permissions within that resource's scope. In the future, roles will be able to include permissions for child resources as well. For example, an organization role will be able to include document permissions for specific projects or all projects.
A user cannot be part of a resource without a role. Each user in an organization must have at least one role assigned to them.
There are both pre-defined and custom roles. Pre-defined roles are included with the product and are not editable, but can be removed from a resource if the feature is enabled.

User

A user is a person that has one or more roles assigned to them.
A user is initially added to a resource via invitation or access request. A user that already has one role can be assigned roles in another project within the same organization or at the organization level without requiring a separate invite.
As an organization owns multiple resources (e.g., projects), any users with roles on these resources are also returned when reading the users of an organization.
If a user has roles in multiple projects, they are considered a single user and can be referenced by their sanityUserId. For example, inviting user A to project B and project C in the same organization will result in a single user with two memberships.

Administrator Rules

Changing Administrators

Only administrators can assign or remove roles with admin permissions. This prevents unauthorized permission elevation.
This rule applies only to the default roles. Custom roles are fully managed by the organization and can be assigned to users without restriction.

Last Administrator

Each resource must have at least one role assigned to at least one user that can read users, read roles, and assign roles to users. This prevents an organization from losing control over their resources.
This is designed as a permission-level check and not a role-level check, so that the default roles can be removed from a resource. Customers with advanced roles management enabled can remove the default roles from a resource.

Breaking Changes from previous versions

See the details of the existing API for a better understanding of the changes.

Summary:

Access is now the root path for managing access-based resources. Previously it was organization and project but these are now nested under the access root.
Internal IDs are no longer exposed for permissions or roles. The name property is now used as the unique identifier for permissions and roles.
Permissions now represent grants, resources, and permissionResourceSchema. These are now legacy terms.
The endpoint /organization/:organizationId/users returns users for all resources owned by the organization. Previously, a client would have to make a request for each resource (e.g., project) individually.
users replaces the term ACL. Users represents individuals assigned roles within the organization.
The pre-defined roles can be completely removed from a resource. Previously, default roles could not be removed from a resource. E.g., a project required at least one project administrator, even if there were custom roles that would cover the same use case.

contact: name: Sanity url: https://sanity.io version: vX servers: - url: https://api.sanity.io description: Production External API tags: - name: Users description: Manage users who have been assigned organization roles. - name: Robots description: Manage robots and robot tokens. - name: Roles description: Manage roles assignable to users of an organization or application. - name: Permissions description: View permissions available to roles within an organization or application. - name: Requests description: Request access to resources. View requests to access resources. - name: Invites description: Manage and accept invites. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT parameters: cursorParam: in: query name: nextCursor required: false schema: type: string description: The cursor for pagination. Use the nextCursor from the previous response to get the next page. limitParam: in: query name: limit required: false schema: type: integer minimum: 1 maximum: 500 default: 100 description: The number of items to return per page. sanityUserIdParam: in: path name: sanityUserId required: true schema: type: string description: The User ID example: gDdcnv42e resourceTypeParam: name: resourceType description: The resource type to scope the access requests to. in: path required: true schema: $ref: '#/components/schemas/ResourceType' resourceIdParam: in: path name: resourceId required: true schema: type: string description: The resource ID to scope the access request to. Must be a valid ID for the resource type. example: 'c7ja4siy' robotIdParam: in: path name: robotId required: true schema: type: string description: The robot's unique identifier. example: 'gJh7daoq4' roleNameParam: in: path name: roleName required: true schema: type: string description: The role name. example: 'administrator' permissionNameParam: in: path name: permissionName required: true schema: type: string description: The name of the permission. This is a unique identifier for the permission. example: 'sanity.project.members.read' requestIdParam: name: requestId in: path required: true schema: type: string description: The ID of the request. includeChildrenParam: in: query name: includeChildren required: false schema: type: boolean description: Whether to include children resources in the response. Only applies to `organization` resources. example: false inviteId: name: inviteId description: The invite's unique identifier. in: path required: true schema: type: string inviteStatus: name: status description: Filter invites by status. in: query required: false style: form explode: true schema: type: array items: $ref: '#/components/schemas/InviteStatus' inviteToken: in: path name: inviteToken required: true schema: type: string description: The public token for the invite. This token is shared with the invitee. responses: badRequest: description: Bad request. forbidden: description: Session is missing required permissions or has the wrong type. resourceNotFound: description: Resource not found. unauthorized: description: Session is not authenticated. schemas: PermissionType: type: string enum: [ sanity.document.filter, sanity.document.filter.mode, sanity.organization, sanity.organization.legal, sanity.organization.members, sanity.organization.projects, sanity.organization.roles, sanity.organization.sso, sanity.organization.tokens, sanity.project, sanity.project.cors, sanity.project.datasets, sanity.project.graphql, sanity.project.members, sanity.project.roles, sanity.project.tags, sanity.project.tokens, sanity.project.usage, sanity.project.webhooks, ] description: The resource for the permission. example: 'sanity.document.filter.mode' PermissionAction: oneOf: - $ref: '#/components/schemas/sanity.document.filter.name' - $ref: '#/components/schemas/sanity.document.filter.mode.name' - $ref: '#/components/schemas/sanity.organization.name' - $ref: '#/components/schemas/sanity.organization.legal.name' - $ref: '#/components/schemas/sanity.organization.members.name' - $ref: '#/components/schemas/sanity.organization.projects.name' - $ref: '#/components/schemas/sanity.organization.roles.name' - $ref: '#/components/schemas/sanity.organization.sso.name' - $ref: '#/components/schemas/sanity.organization.tokens.name' - $ref: '#/components/schemas/sanity.project.name' - $ref: '#/components/schemas/sanity.project.cors.name' - $ref: '#/components/schemas/sanity.project.datasets.name' - $ref: '#/components/schemas/sanity.project.graphql.name' - $ref: '#/components/schemas/sanity.project.members.name' - $ref: '#/components/schemas/sanity.project.roles.name' - $ref: '#/components/schemas/sanity.project.tags.name' - $ref: '#/components/schemas/sanity.project.tokens.name' - $ref: '#/components/schemas/sanity.project.usage.name' - $ref: '#/components/schemas/sanity.project.webhooks.name' PermissionActions: oneOf: - type: array items: $ref: '#/components/schemas/sanity.document.filter' - type: array items: $ref: '#/components/schemas/sanity.document.filter.mode' - type: array items: $ref: '#/components/schemas/sanity.organization' - type: array items: $ref: '#/components/schemas/sanity.organization.legal' - type: array items: $ref: '#/components/schemas/sanity.organization.members' - type: array items: $ref: '#/components/schemas/sanity.organization.projects' - type: array items: $ref: '#/components/schemas/sanity.organization.roles' - type: array items: $ref: '#/components/schemas/sanity.organization.sso' - type: array items: $ref: '#/components/schemas/sanity.organization.tokens' - type: array items: $ref: '#/components/schemas/sanity.project' - type: array items: $ref: '#/components/schemas/sanity.project.cors' - type: array items: $ref: '#/components/schemas/sanity.project.datasets' - type: array items: $ref: '#/components/schemas/sanity.project.graphql' - type: array items: $ref: '#/components/schemas/sanity.project.members' - type: array items: $ref: '#/components/schemas/sanity.project.roles' - type: array items: $ref: '#/components/schemas/sanity.project.tags' - type: array items: $ref: '#/components/schemas/sanity.project.tokens' - type: array items: $ref: '#/components/schemas/sanity.project.usage' - type: array items: $ref: '#/components/schemas/sanity.project.webhooks' description: The actions allowed by the permission for this role. example: ['mode'] sanity.document.filter: type: object properties: name: $ref: '#/components/schemas/sanity.document.filter.name' title: type: string example: 'Create' description: type: string example: 'Create a new document' sanity.document.filter.name: type: string enum: ['create', 'read', 'update', 'manage', 'history', 'editHistory'] sanity.document.filter.mode: type: object properties: name: $ref: '#/components/schemas/sanity.document.filter.mode.name' title: type: string example: 'Mode' description: type: string example: 'Mode of the document filter' sanity.document.filter.mode.name: type: string enum: ['mode'] sanity.organization.members: type: object properties: name: $ref: '#/components/schemas/sanity.organization.members.name' title: type: string example: 'Organization Members' description: type: string example: 'Manage organization members' sanity.organization.members.name: type: string enum: ['invite', 'read', 'update', 'delete'] sanity.project.tokens: type: object properties: name: $ref: '#/components/schemas/sanity.project.tokens.name' title: type: string example: 'Project Tokens' description: type: string example: 'Manage project tokens' sanity.project.tokens.name: type: string enum: ['read', 'create', 'delete'] sanity.project.datasets: type: object properties: name: $ref: '#/components/schemas/sanity.project.datasets.name' title: type: string example: 'Project Datasets' description: type: string example: 'Manage project datasets' sanity.project.datasets.name: type: string enum: ['read', 'create', 'update', 'delete'] sanity.project.usage: type: object properties: name: $ref: '#/components/schemas/sanity.project.usage.name' title: type: string example: 'Project Usage' description: type: string example: 'Read project usage' sanity.project.usage.name: type: string enum: ['read'] sanity.organization.legal: type: object properties: name: $ref: '#/components/schemas/sanity.organization.legal.name' title: type: string example: 'Organization Legal' description: type: string example: 'Manage organization legal documents' sanity.organization.legal.name: type: string enum: ['read', 'update'] sanity.organization.sso: type: object properties: name: $ref: '#/components/schemas/sanity.organization.sso.name' title: type: string example: 'Organization SSO' description: type: string example: 'Manage organization SSO settings' sanity.organization.sso.name: type: string enum: ['saml'] sanity.project.graphql: type: object properties: name: $ref: '#/components/schemas/sanity.project.graphql.name' title: type: string example: 'Project GraphQL' description: type: string example: 'Manage project GraphQL settings' sanity.project.graphql.name: type: string enum: ['manage'] sanity.project: type: object properties: name: $ref: '#/components/schemas/sanity.project.name' title: type: string example: 'Project' description: type: string example: 'Manage project settings' sanity.project.name: type: string enum: ['read', 'update', 'delete', 'createSession', 'deployStudio'] sanity.project.cors: type: object properties: name: $ref: '#/components/schemas/sanity.project.cors.name' title: type: string example: 'Project CORS' description: type: string example: 'Manage project CORS settings' sanity.project.cors.name: type: string enum: ['read', 'create', 'delete'] sanity.project.webhooks: type: object properties: name: $ref: '#/components/schemas/sanity.project.webhooks.name' title: type: string example: 'Project Webhooks' description: type: string example: 'Manage project webhooks' sanity.project.webhooks.name: type: string enum: ['read', 'create', 'delete', 'update'] sanity.project.roles: type: object properties: name: $ref: '#/components/schemas/sanity.project.roles.name' title: type: string example: 'Project Roles' description: type: string example: 'Manage project roles' sanity.project.roles.name: type: string enum: ['create', 'read', 'update', 'delete'] sanity.organization.tokens: type: object properties: name: $ref: '#/components/schemas/sanity.organization.tokens.name' title: type: string example: 'Organization Tokens' description: type: string example: 'Manage organization tokens' sanity.organization.tokens.name: type: string enum: ['read', 'create', 'delete'] sanity.organization: type: object properties: name: $ref: '#/components/schemas/sanity.organization.name' title: type: string example: 'Organization' description: type: string example: 'Manage organization settings' sanity.organization.name: type: string enum: ['read', 'update', 'delete', 'billing'] sanity.project.members: type: object properties: name: $ref: '#/components/schemas/sanity.project.members.name' title: type: string example: 'Project Members' description: type: string example: 'Manage project members' sanity.project.members.name: type: string enum: ['invite', 'read', 'update', 'delete'] sanity.organization.projects: type: object properties: name: $ref: '#/components/schemas/sanity.organization.projects.name' title: type: string example: 'Organization Projects' description: type: string example: 'Manage organization projects' sanity.organization.projects.name: type: string enum: ['read', 'attach', 'detach'] sanity.organization.roles: type: object properties: name: $ref: '#/components/schemas/sanity.organization.roles.name' title: type: string example: 'Organization Roles' description: type: string example: 'Manage organization roles' sanity.organization.roles.name: type: string enum: ['create', 'read', 'update', 'delete'] sanity.project.tags: type: object properties: name: $ref: '#/components/schemas/sanity.project.tags.name' title: type: string example: 'Project Tags' description: type: string example: 'Manage project tags' sanity.project.tags.name: type: string enum: ['read', 'create', 'update', 'delete'] Permission: title: Permission type: object properties: type: $ref: '#/components/schemas/PermissionType' actions: $ref: '#/components/schemas/PermissionActions' name: type: string description: The name of the permission. This is the unique identifier for the resource. example: 'legal-documents' title: type: string description: The human-readable title of the permission. example: 'Permission for "Legal" Folder' description: type: string description: The description of the permission. example: 'Permission for "Legal" Folder' resourceType: type: string description: The resource the permission applies to. example: 'project' resourceId: type: string description: The resource ID the permission applies to. example: 'c7ja4siy' ownerOrganizationId: type: string description: The organization ID the permission applies to. Used for wildcard permissions where the resourceId is `*`. example: 'or0Bc1hcJ' params: type: object description: The parameters for the permission. This is a key-value map of the permission's configuration. example: {filter: '*[_type == "legal"]'} required: - type - name - title - resourceType - resourceId Role: title: Role type: object properties: name: type: string example: 'administrator' title: type: string example: 'Administrator' description: type: string example: 'Administrators can manage billing details, legal contacts, organization users, and manage project ownership.' isCustom: type: boolean example: false resourceType: type: string example: 'organization' resourceId: type: string example: 'or0Bc1hcJ' appliesToUsers: type: boolean example: true appliesToRobots: type: boolean example: true permissions: type: array items: type: object properties: type: $ref: '#/components/schemas/PermissionType' action: $ref: '#/components/schemas/PermissionAction' name: type: string description: The name of the permission. example: 'legal-documents' params: type: object description: The parameters for the permission. This is a key-value map of the permission's configuration. example: {dataset: 'development'} required: - name - title - resourceType - resourceId - appliesToUsers - appliesToRobots Membership: type: object properties: addedAt: type: string format: date-time example: '2024-01-15T12:15:30Z' resourceType: type: string example: 'project' resourceId: type: string example: 'c7ja4siy' roleNames: type: array items: type: string example: ['administrator', 'editor'] lastSeenAt: type: string format: date-time nullable: true example: '2024-01-15T12:15:30Z' required: - resourceType - resourceId - roleNames Memberships: type: array items: $ref: '#/components/schemas/Membership' User: title: User type: object properties: sanityUserId: type: string example: 'gDdcnv42e' profile: $ref: '#/components/schemas/UserProfile' memberships: $ref: '#/components/schemas/Memberships' required: - sanityUserId - profile - memberships Request: type: object properties: id: type: string example: 'request-id' status: type: string example: 'pending' resourceId: type: string example: 'project-id' resourceType: type: string example: 'project' createdAt: type: string format: date-time example: '2024-07-10T12:00:00Z' updatedAt: type: string format: date-time example: '2024-07-10T12:00:00Z' updatedByUserId: type: string example: 'admin-id' requestedByUserId: type: string example: 'user-id' note: type: string example: 'Text describing the reason of the request.' requestedByUserProfile: $ref: '#/components/schemas/UserProfile' type: $ref: '#/components/schemas/RequestType' requestedRole: type: string example: 'editor' required: - id - status - resourceId - resourceType - createdAt - requestedByUserId ResourceType: type: string enum: [organization, project] example: project description: | Resources are entities that can be managed and accessed through the Access API. Robot: type: object description: A robot is a service account that can be used to authenticate with the API. properties: id: type: string description: The unique identifier for the robot. readOnly: true label: type: string description: A human-readable label for the robot. createdAt: type: string format: date-time description: The creation date of the robot. readOnly: true memberships: $ref: '#/components/schemas/Memberships' required: - id - label - createdAt - memberships RobotWithToken: type: object allOf: - $ref: '#/components/schemas/Robot' properties: token: type: string description: The secret token for the robot. readOnly: true required: - token Invite: type: object properties: id: type: string status: $ref: '#/components/schemas/InviteStatus' resourceType: $ref: '#/components/schemas/ResourceType' resourceId: type: string role: type: string email: type: string description: | The email address of the invitee. Only present if the invite is still pending. inviterType: $ref: '#/components/schemas/InviterType' inviterId: type: string description: | The ID of the user or service that created the invite. Only present if the invite was created by a user. inviteeId: type: string description: | The ID of the user that accepted the invite. Only present if the invite has been accepted. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - status - resourceType - resourceId - role - inviterType - createdAt - updatedAt InviteStatus: type: string enum: [pending, accepted, revoked] InviterType: type: string enum: [user, service] UserProfile: type: object properties: id: type: string displayName: type: string email: type: string familyName: type: string givenName: type: string middleName: type: string nullable: true imageUrl: type: string format: uri provider: type: string tosAcceptedAt: type: string format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time isCurrentUser: type: boolean providerId: type: string required: - id - displayName - email - provider - createdAt RequestType: type: string enum: [access, role] example: access description: The type of request. PaginatedResponse: type: object properties: data: type: array items: type: object nextCursor: type: string nullable: true description: Cursor to get the next page of results, `null` if there are no more results. required: - data - nextCursor UserPermission: type: object properties: name: type: string description: The name of the permission. example: 'sanity-project-members' type: type: string description: The type of the permission. example: 'sanity.project.members' action: $ref: '#/components/schemas/PermissionAction' example: 'read' resourceType: $ref: '#/components/schemas/ResourceType' example: 'project' resourceId: type: string example: 'project-id' params: type: object description: The parameters for the permission. This is a key-value map of the permission's configuration. example: {dataset: 'development'} required: - name - action - resourceType - resourceId requestBodies: CreateRobotRequestBody: required: true content: application/json: schema: type: object properties: label: type: string description: A human-readable label for the robot. example: 'My Robot' memberships: $ref: '#/components/schemas/Memberships' required: - label - memberships CreateInviteRequestBody: required: true content: application/json: schema: type: object properties: email: type: string role: type: string required: - email - role RoleRequestBody: required: true content: application/json: schema: type: object properties: title: type: string minLength: 1 maxLength: 100 example: 'Custom Role' name: type: string pattern: '^[a-z0-9-_]+$' example: 'custom-role' description: type: string default: '' example: 'Custom role for project' appliesToUsers: type: boolean default: true appliesToRobots: type: boolean default: true permissions: type: array items: type: object properties: name: type: string description: The name of the permission. example: 'legal-documents' action: $ref: '#/components/schemas/PermissionAction' params: type: object description: The parameters for the permission. This is a key-value map of the permission's configuration. example: {dataset: 'development'} required: - title - name - resourceType - resourceId - appliesToUsers - appliesToRobots - permissions PermissionRequestBody: content: application/json: schema: type: object properties: type: $ref: '#/components/schemas/PermissionType' name: type: string description: The name of the permission resource. A unique identifier for a permission. example: 'legal-documents' title: type: string description: A human-readable title of the permission resource. This is used for display purposes. example: 'Permission for "Legal" Folder' description: type: string description: The description of the permission resource. example: 'Permission for "Legal" Folder' config: type: object description: Some permissions allow for additional configuration when used with document permissions. Accepts a groq filter or a dataset name. example: {'filter': "*[_type == 'legal']"} required: - type - name - title - description security: - bearerAuth: [] paths: /vX/access/{resourceType}/{resourceId}/permissions: get: summary: Get Permissions. description: > Gets the available permissions within the scope of a resource. These permissions can be applied to roles and are used to determine user/robot access to resources.

Requires permission: `sanity.{resourceType}.roles.read` operationId: getPermissions tags: - Permissions parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of permission resources for the resource content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Permission' '404': description: Resource not found '401': description: Unauthorized '400': description: Bad request post: summary: Create a permission. description: > Creates a custom permission on a resource.

Requires permission: `sanity.{resourceType}.roles.create`
Requires feature: `advancedRolesManagement`

See Example. It creates a permission to allow a user to read legal documents in project `c7ja4siy` and dataset `production`. operationId: createPermission tags: - Permissions parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' requestBody: $ref: '#/components/requestBodies/PermissionRequestBody' responses: '201': description: Permission resource created successfully content: application/json: schema: $ref: '#/components/schemas/Permission' '400': description: Bad request '401': description: Unauthorized /vX/access/{resourceType}/{resourceId}/permissions/{permissionName}: get: summary: Get a permission description: > Gets a permission for a resource by name. Requires permission - `sanity.{resourceType}.roles.read` operationId: getPermission tags: - Permissions parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/permissionNameParam' responses: '200': description: The permission resource for the resource content: application/json: schema: $ref: '#/components/schemas/Permission' '404': description: Resource not found '401': description: Unauthorized '400': description: Bad request put: summary: Update a permission description: > Updates a permission for a resource. Requires permission - `sanity.{resourceType}.roles.update` Requires feature: - `advancedRolesManagement` operationId: updatePermission tags: - Permissions parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/permissionNameParam' requestBody: $ref: '#/components/requestBodies/PermissionRequestBody' responses: '200': description: Permission resource updated successfully content: application/json: schema: $ref: '#/components/schemas/Permission' '404': description: Resource not found '401': description: Unauthorized '400': description: Bad request delete: summary: Delete a permission description: > Deletes a specific permission for a resource. Can only be used with custom permissions. Requires permission - `sanity.{resourceType}.roles.delete` Requires feature: - `advancedRolesManagement` operationId: deletePermission tags: - Permissions parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/permissionNameParam' responses: '200': description: Permission deleted successfully '404': description: Resource not found '401': description: Unauthorized '400': description: Bad request /vX/access/permissions/me: get: summary: Get current user permissions. description: > Gets the available permissions within the scope of a resource. These permissions can be applied to roles and are used to determine user/robot access to resources. operationId: getMyPermissions tags: - Permissions parameters: - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of permissions for all resources the current user has access to content: application/json: schema: type: array items: $ref: '#/components/schemas/Permission' /vX/access/{resourceType}/{resourceId}/user-permissions/me: get: summary: Get current user permissions. description: > Gets current user permissions within scope of a resource. These permissions can be applied to roles and are used to determine user/robot access to resources. operationId: getUserPermissions tags: - Permissions parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of permissions for all resources the current user has access to content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/UserPermission' /vX/access/{resourceType}/{resourceId}/users: get: summary: List all users of a resource and their assigned roles. description: > Retrieve a list of all users of a resource along with their assigned roles. When the resourceType is `organization`, this endpoint will return users of projects owned by the organization. Requires permission - `sanity.{resourceType}.members.read` operationId: getUsers tags: - Users parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of resource users and their assigned roles content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/User' totalCount: type: integer description: Total number of users available example: 1 required: - totalCount '404': description: Resource not found '401': description: Unauthorized '400': description: Bad request /vX/access/organization/{resourceId}/users/roles/default: put: summary: Apply organization default role to all users. tags: - Users description: > Add default role to all resource users. Limited to Organization. Requires permission - `sanity.organization.members.update` operationId: addDefaultRoleToUsers parameters: - $ref: '#/components/parameters/resourceIdParam' responses: '201': description: Roles assigned to the resource users '400': description: Invalid input '404': description: Resource not found /vX/access/{resourceType}/{resourceId}/users/{sanityUserId}: get: summary: Get user and roles. description: Get the users for a single user of a resource. Requires permission - `sanity.{resourceType}.members.read` operationId: getUser tags: - Users parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/sanityUserIdParam' responses: '200': description: Get resource user and their roles. content: application/json: schema: $ref: '#/components/schemas/User' '404': description: Resource not found '400': description: Bad request delete: summary: Remove a user from a resource. description: > This removes all roles. If the resourceType is `organization`, this will also remove the user from all projects owned by the organization. Requires permission - `sanity.{resourceType}.members.delete` operationId: removeUser tags: - Users parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/sanityUserIdParam' responses: '200': description: User removed from the resource '400': description: Invalid input '404': description: Resource not found /vX/access/{resourceType}/{resourceId}/users/{sanityUserId}/roles/{roleName}: put: summary: Add a role to a user. description: > Add a role to a user. Requires permission - `sanity.{resourceType}.members.update` operationId: addRoleToUser tags: - Users parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/sanityUserIdParam' - $ref: '#/components/parameters/roleNameParam' responses: '201': description: Role assigned to the user content: application/json: schema: $ref: '#/components/schemas/User' '400': description: Invalid input '404': description: Resource not found delete: summary: Remove a role from a user in a resource. description: > You cannot remove the last role from a user. You must have at least one role assigned to a user. Requires permission - `sanity.{resourceType}.members.update` operationId: removeRoleFromUser tags: - Users parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/sanityUserIdParam' - $ref: '#/components/parameters/roleNameParam' responses: '200': description: Role removed from user '400': description: Invalid input '404': description: Resource not found /vX/access/{resourceType}/{resourceId}/users/{sanityUserId}/permissions: get: summary: List permissions for a user description: > Normalized list of permission resources for a user across all assigned roles. Requires permissions: - `sanity.{resourceType}.members.read` for resource scoped roles (e.g. project admin) operationId: getuserPermissions tags: - Users parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/sanityUserIdParam' responses: '200': description: List permissions for a user content: application/json: schema: type: array items: $ref: '#/components/schemas/Permission' /vX/access/{resourceType}/{resourceId}/roles: get: summary: List roles assignable to a user on this resource. description: > Requires permission - `sanity.{resourceType}.roles.read` operationId: getRoles tags: - Roles parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/includeChildrenParam' - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of roles for a resource content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Role' post: summary: Create a role description: > Requires permission: - `sanity.{resourceType}.roles.create` Requires feature: - `advancedRolesManagement` operationId: createRole tags: - Roles parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' requestBody: $ref: '#/components/requestBodies/RoleRequestBody' responses: '201': description: Role created content: application/json: schema: $ref: '#/components/schemas/Role' '400': description: Invalid input '401': description: Unauthorized '404': description: Resource not found /vX/access/{resourceType}/{resourceId}/roles/{roleName}: get: summary: Get a role description: > Requires permission - `sanity.{resourceType}.roles.read` operationId: getRole tags: - Roles parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/roleNameParam' responses: '200': description: Get a role content: application/json: schema: $ref: '#/components/schemas/Role' '404': description: Role not found '401': description: Unauthorized put: summary: Update a role description: > Requires permission: - `sanity.{resourceType}.roles.update` Requires feature: - `advancedRolesManagement` Replaces existing object values including permissions. operationId: updateRole tags: - Roles parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/roleNameParam' requestBody: $ref: '#/components/requestBodies/RoleRequestBody' responses: '200': description: Role updated content: application/json: schema: $ref: '#/components/schemas/Role' '400': description: Invalid input '401': description: Unauthorized '404': description: Role not found '403': description: Forbidden. Only custom roles can be changed. delete: summary: Delete a role description: > Requires permission: - `sanity.{resourceType}.roles.delete` for resource scoped roles (e.g. project admin) Requires feature: - `advancedRolesManagement` Cannot delete a role that is assigned to a user. The role needs to be removed from users first. operationId: deleteRole tags: - Roles parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/roleNameParam' responses: '200': description: Role deleted '401': description: Unauthorized '404': description: Role not found /v2024-07-01/access/{resourceType}/{resourceId}/requests: get: summary: List all requests for given project/organization. description: 'Permissions `sanity.{resourceType}.members.read`' operationId: getRequests tags: - Requests parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/includeChildrenParam' responses: '200': description: A list of resource requests content: application/json: schema: type: array items: $ref: '#/components/schemas/Request' '400': description: Bad request '404': description: Request not found '401': description: Unauthorized post: summary: Create a new Request description: Creates a new request for the given project/organization. Requires an authenticated user. operationId: createRequest tags: - Requests parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' requestBody: description: Request data to create required: true content: application/json: schema: type: object properties: note: type: string example: 'Text describing the reason of the request' requestUrl: type: string example: 'https://sanity-studio.mycompany.io/doc/1234567890' description: > Optional URL to redirect the user to after their request has been accepted. Do not include PII or other confidential information. requestedRole: type: string example: 'editor' description: > Optional role requested by the user. The approver can assign a different role, but this is just a suggestion. If the role does not exist, the request will still be created and no validation on the role will be done. type: $ref: '#/components/schemas/RequestType' responses: '201': description: Request created successfully content: application/json: schema: $ref: '#/components/schemas/Request' '400': description: Bad request '404': description: Request not found '401': description: Unauthorized '409': description: Conflict content: application/json: schema: type: object properties: message: type: string example: oneOf: - The email domain is not allowed - Request Access feature is disabled for organization /v2024-07-01/access/{resourceType}/{resourceId}/requests/{requestId}/accept: put: summary: Accept request description: 'Permissions `sanity.{resourceType}.members.invite`' operationId: acceptRequest tags: - Requests parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/requestIdParam' requestBody: description: Request data to update required: true content: application/json: schema: type: object properties: roleNames: type: array items: type: string example: 'admin' responses: '200': description: Request accepted successfully content: application/json: schema: $ref: '#/components/schemas/Request' '400': description: Bad request '404': description: Request not found '401': description: Unauthorized /v2024-07-01/access/{resourceType}/{resourceId}/requests/{requestId}/decline: put: summary: Decline request description: 'Permissions `sanity.{resourceType}.members.invite`' operationId: declineRequest tags: - Requests parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/requestIdParam' responses: '200': description: Request declined successfully content: application/json: schema: $ref: '#/components/schemas/Request' '400': description: Bad request '404': description: Request not found '401': description: Unauthorized /v2024-07-01/access/requests/me: get: summary: List all request for current user description: Requires an authenticated user. operationId: getMyRequests tags: - Requests responses: '200': description: A list of user Requests content: application/json: schema: type: array items: $ref: '#/components/schemas/Request' '400': description: Bad request '404': description: Request not found '401': description: Unauthorized /vX/access/{resourceType}/{resourceId}/invites: get: tags: [Invites] operationId: getInvites summary: Get invites description: | Retrieves a list of invites for the specified resource. Only pending invites are retrieved by default. Use the optional `status` parameter to change the filter behavior. You can select multiple statuses by repeating the parameter. ### Children invites By default, only invites for the specified resource are returned. Use the optional `includeChildren` parameter to include invites for children resources as well. This only applies to `organization` resources. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.members.read` parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/inviteStatus' - $ref: '#/components/parameters/includeChildrenParam' - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of invites content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Invite' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/resourceNotFound' post: tags: [Invites] operationId: createInvite summary: Create invite description: | Creates an invite for the specified resource. The invitee will receive an email with a link to accept the invite. Each invitee can only receive one invite per resource and role. Attempting to create an invite using a non-existent role, or a role that cannot be granted to users will result in a Bad Request error. ### Unavailable resources If the underlying resource is unavailable then a Bad Request error will be returned. A common example of an unavailable resource is a project that is blocked or archived. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.members.invite` Additionally, only administrators can invite other administrators. parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' requestBody: $ref: '#/components/requestBodies/CreateInviteRequestBody' responses: '201': description: Invite created. content: application/json: schema: $ref: '#/components/schemas/Invite' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/resourceNotFound' /vX/access/{resourceType}/{resourceId}/invites/{inviteId}: delete: tags: [Invites] operationId: revokeInvite summary: Revoke invite description: | Revokes an invite. Attempting to revoke an invite that has already been accepted or revoked will result in a Bad Request error. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.members.invite` parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/inviteId' responses: '204': description: Invite revoked. '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': description: Resource or invite not found. /vX/access/{resourceType}/{resourceId}/invites/token/{inviteToken}: get: tags: [Invites] operationId: getInviteByToken summary: Get invite description: | Retrieves an invite using its token. ### Authorization This endpoint does not require authentication. parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/inviteToken' responses: '200': description: Invite found. content: application/json: schema: $ref: '#/components/schemas/Invite' '404': description: Resource or invite not found. /vX/access/{resourceType}/{resourceId}/invites/token/{inviteToken}/accept: post: tags: [Invites] operationId: acceptInvite summary: Accept invite description: | Accepts an invite using its token. Attempting to accept an invite that is already accepted or revoked will result in a Bad Request error. Once the invite has been accepted, the user will have access to the resource with the role assigned as part of the invitation. > **Access is propagated internally and may take a up to a few minutes to > be fully available across all systems.** ### Unavailable resources If the underlying resource is unavailable then a Bad Request error will be returned. A common example of an unavailable resource is a project that is blocked or archived. ### Member quota Some resources have a limit on the number of members. If accepting an invite would go over this limit, then a Payment Required error is returned. ### Authorization This endpoint requires an authenticated user session. parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/inviteToken' responses: '204': description: Invite accepted. '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '402': description: Resource reached its allowed number of members. '403': $ref: '#/components/responses/forbidden' '404': description: Resource or invite not found. /vX/access/{resourceType}/{resourceId}/robots: get: tags: [Robots] operationId: getRobots summary: Get robots with access to this resource description: | Retrieves a list of robots that have access to the specified resource. ### Access to children resources By default, this endpoint returns robots that have at least one role on the specified resource. Use the optional `includeChildren` parameter to include robots that have a role on children resources as well. This only applies to `organization` resources. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.tokens.read` parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/includeChildrenParam' - $ref: '#/components/parameters/cursorParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A paginated list of robots content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Robot' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/resourceNotFound' post: tags: [Robots] operationId: createRobot summary: Create robot and associated token description: | Creates a robot with the specified role grants and returns its secret token. The API currently only supports organization-scoped robots. This means that `organization` must be provided to the `resourceType` parameter. Only the specified resource and its children resources can be specified in the role grants. The robot will not have access to other resources. ### Secret token The secret token is only returned once and can not be retrieved again. If the token is lost, a new robot must be created. The previous robot should be deleted. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.tokens.create` parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' requestBody: $ref: '#/components/requestBodies/CreateRobotRequestBody' responses: '201': description: Robot created. content: application/json: schema: $ref: '#/components/schemas/RobotWithToken' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/resourceNotFound' /vX/access/{resourceType}/{resourceId}/robots/{robotId}: get: tags: [Robots] operationId: getRobot summary: Get robot metadata description: | Retrieves a robot using its unique identifier. It's not possible to retrieve a robot token. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.tokens.read` parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/robotIdParam' responses: '200': description: Robot found. content: application/json: schema: $ref: '#/components/schemas/Robot' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '404': description: Resource or robot not found. delete: tags: [Robots] operationId: deleteRobot summary: Delete robot and associated token description: | Deletes a robot and revokes its token. ### Authorization This endpoint requires an authenticated user session with the following permissions: - `sanity.{resourceType}.tokens.delete` parameters: - $ref: '#/components/parameters/resourceTypeParam' - $ref: '#/components/parameters/resourceIdParam' - $ref: '#/components/parameters/robotIdParam' responses: '204': description: Robot deleted. '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '404': description: Resource or robot not found.