I’ve been trying to create a new permissions document. I tried using sanity exec But I get the error: ClientError: The mutation(s) failed: mutation failed on document

You're getting this error because you can't create permissions documents directly through mutations. The _.groups documents you're trying to create are internal system documents that Sanity manages behind the scenes—they're not meant to be created or modified directly via sanity exec or standard content mutations.

The Correct Way to Create Permissions

Roles and permissions in Sanity should be managed through the proper channels, not by creating documents. Here are the officially supported methods:

Option 1: Use the Web Interface (Easiest)

The most straightforward way to create and manage roles is through the web interface at sanity.io/manage:

1. Go to sanity.io/manage
2. Select your project
3. Navigate to the "Roles" section
4. Create custom roles with the permissions you need

This interface handles all the underlying permission configuration for you and ensures everything is properly validated.

Option 2: Use the Management API's Roles API (For Programmatic Access)

If you need to create or manage roles programmatically, use the Management API's Roles API. This is the official HTTP API for managing roles, permissions, and access control.

The Roles API provides proper endpoints for:

• Creating custom roles
• Defining content resources with GROQ filters
• Assigning permissions to roles
• Managing role assignments

This requires an admin-level API token but works within the supported permission boundaries and is the maintainable, officially supported approach.

Important Context

The error message mentioning "manage" permissions is telling you that even if you had elevated credentials, you still couldn't create _.groups documents directly—they're part of Sanity's internal access control infrastructure. The platform manages these system documents automatically when you use the proper interfaces (web UI or Roles API).

Enterprise Feature Requirement

Keep in mind that custom roles are an Enterprise-only feature. If you're not on an Enterprise plan, you're limited to Sanity's default roles (Administrator, Editor, Viewer, Developer, and Contributor) and cannot create custom permission configurations.

The key takeaway: Don't try to create permissions documents directly. Always use either the web interface at sanity.io/manage or the Management API's Roles endpoints to manage your project's access control.