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

Content permissions are environment-specific. If you are working with multiple environments, you must configure permissions separately for each one. You can configure up to 50 content permissions in a project environment. You can distribute these across the unauthenticated Content API, PATs, and custom roles as needed.

#Permission actions

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

For custom roles

Custom roles have no content permissions by default. At a minimum, a custom role that uses the content editor need the following permissions:

• Read access on the User system model. This is important for custom roles that interact with the UI, as user attribution fields (createdBy, updatedBy, and publishedBy) will not display without these permissions. Missing these permissions can also cause not allowed errors when mutating content from the content editor. See System fields: User fields for more information.
• Read versions. This is required for versioning to display correctly in the content editor.

#Set up unauthenticated access to the Content API

Unauthenticated requests to the Content API are intended for reads. To expose published content publicly:

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 default public content delivery stage, which is PUBLISHED unless you changed it.
3. If you need custom rules instead, click Add permissions, select All models, check Read, leave Locales and Stages at their defaults, and click Create.

The Content API now serves that content to unauthenticated requests.

For the add, edit, and delete steps on this screen, see Unauthenticated requests: Content API. For what each action means, see Permission actions.

Content API read permissions for unauthenticated requests

Learn more about authorization.

#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.

For the general add permission steps on a PAT, see Authenticated requests: Permanent Auth Tokens. For what each action means, see Permission actions.

#Scope content permissions

The examples below show how to scope a content permission in the UI. They apply when you add a permission on a custom role, a Permanent Auth Token, or the unauthenticated Content API.

For combined permission sets for a job, such as a read-only reviewer or a publisher, see Permission combinations by job.

#By model

Select the target model from the Model dropdown when creating a content permission. Permissions will apply only to entries of that model.

Setup by models

#By locale

When selecting a permission action, use the Locales dropdown to restrict it to one or more specific locales.

To create or update a document with non-localized fields, the user or token must have access to the default locale. If no default locale is set, the user or token must have access to all locales.

Setup by locales

#By content stage

Use the From stages and To stages dropdowns to restrict publish and unpublish actions to specific stages. For example, you can limit a role to publishing from Draft to a QA stage only, preventing direct publishing to Published.

Setup by content stage

#By environment

Management API permissions apply to all environments in a project. Content permissions are environment-specific, so you can configure different permissions on each environment for the same role.

For example, to give a role read-only access on the master environment and publish access on a secondary environment:

1. Switch to your master environment.
2. Set up the role as read-only, as described in Content reviewer.
3. Switch to the secondary environment. Learn how to switch environments.
4. Open the custom role and select View permissions.
5. Add the Publish and Unpublish content permissions.
6. Enable the additional Management API permissions required for publishing, as described in Publisher.

Setup by environment

#Use conditions

Conditions let you restrict a permission to specific content entries. Instead of granting a role, token, or the public Content API access to all entries in a model, you can scope it further using a GraphQL where clause. For example, for entries with a particular field value, tag, or ID.

Conditions require familiarity with GraphQL where clauses. Use the API Playground to build and test a condition before applying it to a role. To add a condition when configuring a permission:

1. Open the custom role, Permanent Auth Token, or public Content API permissions screen, and click Add permissions.
2. Select the target model from the Model dropdown.
3. Check the actions you want to grant.
4. Enter a JSON where clause in the Condition field.
5. Click Create to save.

Conditions

You need to maintain conditions manually. If a field is renamed or a referenced document ID changes, the condition becomes invalid. Update affected conditions whenever the underlying schema or content changes.

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

#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 permissions.