Content permissions control who can read, create, update, delete, publish, and unpublish content in your Hygraph project. You can configure permissions for unauthenticated Public API access, individual Permanent Auth Tokens (PATs), and custom roles.

Content permissions are environment-specific. Their configuration is applied per environment. If you are working with multiple environments, you must configure permissions separately for each one.

#Permission actions

The permission system is built on seven action types. Granting an action gives the Public API, a PAT, or a custom role permissions to perform that action on all models or a specific model.

#Set up Public API access

The Public API is read-only. To expose content publicly via the API:

1. Navigate to Project Settings > Access > Content API.
2. In the Content Permissions box, click Initialize defaults. This sets Read permissions on all models for the PUBLISHED stage.
3. If you need custom rules instead, click + Add permission, select All models, check Read, leave Locales and Stages at their defaults, and click Create.

The Public API is now accessible with read permissions.

Public API Read Permissions

Learn more about working with the Public API.

#Set up a PAT with model-specific permissions

A Permanent Auth Token (PAT) can be scoped to specific models and actions. The example below configures a PAT that can read, create, and update entries in a Post model only.

1. Navigate to Project Settings > Access > Permanent Auth Tokens and click + Add Token.
2. Enter a token name and optional description, then click Add & configure permissions.
3. Under Content API in the token detail view, click Add permissions.
4. Select the Post model and check Read, Create, and Update. Leave Locales, Stages, and Condition at their defaults, then click Create.

The token can now read, create, and update Post entries.

With this configuration, the token cannot access related models such as Author, Asset, or SEO. To connect posts to those models, add separate permissions for each.

PAT Post Permissions

Learn more about authenticating with a PAT.

#Use conditions

Conditions let you restrict a permission to a subset of content entries. This section covers the syntax and constraints for writing conditions. For a walkthrough of how to add a condition to a role in the Hygraph UI, see Using conditions in role setup.

To define a condition, write a where clause in JSON and paste it into the Condition field when creating or editing a permission for a specific model.

Build and test your where clause in the API Playground before adding it as a condition.

The following examples show conditions applied to a Post model:

• Grant access only to posts tagged with specific values:

  { "tags_contains_some": ["GraphQL", "SEO"] }

  Copy

• Extend the above to also include posts with no tags:

  { "OR": [{ "tags_contains_some": ["GraphQL", "SEO"] }, { "tags": null }] }

  Copy

  PAT Post Tag Conditions

• Restrict access to posts related to a specific author by ID:

  { "author": { "id_in": ["ckadqgca800ix011230ailipe"] } }

  Copy

  For this to work, the token or role also needs read access on the Author model. You can optionally restrict that access to a single document:

  { "id": "ckadqgca800ix011230ailipe" }

  Copy

  PAT Post Author Conditions

#Limits and considerations

#Total permissions per environment

You can configure up to 50 content permissions in a project environment. You can distribute these across the Public API, PATs, and custom roles as needed.

Learn more about working with environments.

#User system model and user attribution

Depending on what you need to expose, you may need to include Read access to the User system model. This is especially important for custom roles that interact with the UI, as user attribution fields (createdBy, updatedBy, and publishedBy) will not display without the appropriate permissions. Missing these permissions can also cause not allowed errors when mutating content from the content editor.

See System fields — User fields for more detail.

#Custom roles

Custom roles have no permissions by default. At a minimum, a custom role needs:

• Read access on the User system model (required for user attribution to work in the UI)
• Read versions (required for versioning to display correctly in the content editor)

#Conditions

Conditions must be kept up to date manually. If a field referenced in a condition is renamed or removed, or a related model changes, the condition will no longer be valid. The same applies when conditions reference specific document IDs.

Conditions cannot be applied to localized fields and do not support search capabilities.

#Relations

When permissions are set on a model that has relations, permissions may be required on both models. For example, in a schema with Post and Author models, updating a Post to connect it to an Author also requires update permissions on the Author model, since an author can reference many posts.

Learn more about relations.

#Locales

Permissions support locale-specific configuration. To create or update a document with non-localized fields, the user or token must have access to the default locale.

#What's next

• Authorization: Public API permissions, PATs, and endpoints.
• Roles and permissions: Create and configure roles, assign permissions, and set up role-based access.
• API access: Manage API endpoints, Permanent Auth Tokens, and Content API permissions.