Hygraph (GraphCMS) Roles & Permissions | OpsBlu Docs

Hygraph (GraphCMS) Roles & Permissions

Hygraph (formerly GraphCMS) role system -- built-in and custom roles, content stage permissions, and API token management.

Hygraph (formerly GraphCMS) is a GraphQL-native headless CMS with a sophisticated role and permission system including content stage-based access control.

Built-in Roles

Role Manage Project Manage Schema Manage Content Publish Content Manage Team API Tokens
Owner Yes Yes Yes Yes Yes Yes
Admin No Yes Yes Yes Yes Yes
Editor No No Yes Yes No No
Contributor No No Yes (drafts) No No No
Viewer No No Read-only No No No

Content Stages

Hygraph supports content stages (Draft, Published, custom stages). Roles interact with stages:

  • Editor can move content between Draft and Published
  • Contributor can only create/edit in Draft stage
  • Viewer can read all stages they have access to

Custom Roles (Paid Plans)

Create custom roles via Settings > Access > Roles:

# Hygraph permissions are defined per-model and per-stage
# Example custom role configuration (via UI):
#
# Role: "Analytics Writer"
# Permissions:
#   - Model "Blog Post": Create, Read, Update (Draft stage only)
#   - Model "Landing Page": Read (all stages)
#   - Model "Analytics Config": Read, Update (all stages)
#   - No schema management access
#   - No publishing permissions

API Token Scopes

Hygraph uses Permanent Auth Tokens with configurable permissions:

# Content API (read-only, safe for client-side)
curl -X POST "https://api-{region}.hygraph.com/v2/{project-id}/master" \
  -H "Authorization: Bearer YOUR_PAT" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ blogPosts { title slug } }"}'

# Management API (full CRUD, server-side only)
curl -X POST "https://management-{region}.hygraph.com/v2/{project-id}/master" \
  -H "Authorization: Bearer YOUR_MGMT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { createBlogPost(data: {title: \"New\"}) { id } }"}'
Token Type Read Create Update Delete Schema
Content API (read) Yes No No No No
Content API (read/write) Yes Yes Yes Yes No
Management API Yes Yes Yes Yes Yes

Analytics Permissions

Since Hygraph is headless, analytics scripts live in your frontend. Hygraph webhooks can trigger on content changes:

{
  "url": "https://your-app.com/api/analytics-webhook",
  "triggers": ["PUBLISH", "UNPUBLISH"],
  "models": ["BlogPost", "LandingPage"]
}

Best Practices

  1. Use Contributor role for writers who should not publish directly
  2. Create custom roles to restrict access to specific content models
  3. Use read-only Content API tokens on client-side, management tokens only server-side
  4. Set up webhooks for content publish events to sync with analytics
  5. Use content stages to create approval workflows before publishing
Back to top