Graphcms User Management: Roles and Permissions | OpsBlu Docs

Graphcms User Management: Roles and Permissions

Manage user roles, permissions, and team access in Graphcms — step-by-step admin guide.

This section covers user management, roles, and permissions for GraphCMS (now Hygraph) and associated analytics tools. GraphCMS rebranded to Hygraph in 2022, offering a GraphQL-native headless CMS for federated content management.

Overview

Hygraph (formerly GraphCMS) provides enterprise-grade user management designed for development teams working with modern, API-first content infrastructure. The platform emphasizes GraphQL APIs while offering comprehensive collaboration features and fine-grained access controls.

Note: GraphCMS rebranded to Hygraph in June 2022. The product and features remain the same, but all branding, documentation, and URLs now use Hygraph.

User management in Hygraph features:

  • Cloud-based team administration through Hygraph dashboard
  • Role-based access control with customizable permissions
  • Permanent Auth Tokens for API access
  • Project-based organization separating teams and content
  • Stage-based permissions for content workflows
  • Audit logging for compliance and security
  • SSO support on Enterprise plans

Hygraph is ideal for multi-channel content delivery, headless websites, mobile apps, and content federation requiring GraphQL APIs.

Platform User Management

Accessing User Management

To manage users in Hygraph:

  1. Log in to Hygraph at app.hygraph.com
  2. Select your project
  3. Navigate to Settings > Team Members or Access
  4. View current team members, roles, and API tokens

User management capabilities depend on your subscription plan, with Enterprise plans offering advanced features like SSO and custom roles.

Hygraph User Roles

Hygraph provides a sophisticated role system with default roles and custom role creation:

Owner

Project owners have complete control:

  • Full access to all project content and settings
  • Can manage all team members and permissions
  • Control over billing and subscription
  • Can create, modify, and delete models and fields
  • Full access to all API tokens and webhooks
  • Can configure integrations and extensions
  • Can delete the project
  • Access to all environments and stages

When to use: Assigned to project creator. Typically 1-2 owners per project.

Admin

Administrators have broad permissions:

  • Manage content across all models and stages
  • Can create and modify content models
  • Can invite and manage team members (except owners)
  • Cannot access billing settings
  • Cannot delete the project
  • Full access to webhooks and API tokens
  • Can configure content stages and locales

When to use: Assign to senior team leads who need comprehensive access.

Developer

Developers focus on technical implementation:

  • Can create and modify content models and fields
  • Full access to API tokens and GraphQL playground
  • Can configure webhooks and remote sources
  • Can publish and unpublish content
  • Cannot manage users or billing
  • Access to all development tools
  • Can modify API permissions

When to use: Assign to software engineers integrating Hygraph.

Content Editor

Editors manage content creation and publication:

  • Can create, edit, and publish content
  • Upload and manage assets
  • Cannot modify content models or schemas
  • Cannot access API tokens or webhooks
  • Cannot manage users or settings
  • Can work across all content locales
  • Access to content scheduling

When to use: Assign to content managers and editorial teams.

Content Contributor

Contributors create content with limited permissions:

  • Can create and edit their own content
  • Can save drafts
  • Cannot publish without approval (configurable)
  • Cannot edit others' content
  • Limited asset upload permissions
  • Cannot modify models or settings
  • Can view published content

When to use: Assign to writers who need editorial oversight.

Viewer

Read-only access for stakeholders:

  • Can view all content and models
  • Cannot create or modify anything
  • Cannot access API tokens
  • Cannot manage users
  • Useful for stakeholders and auditors
  • Can export content data

When to use: Assign to stakeholders who need visibility without edit access.

Custom Roles and Permissions

Enterprise plans support granular custom roles:

Creating Custom Roles

  1. Navigate to Settings > Roles & Permissions
  2. Click Create Custom Role
  3. Define role name and description
  4. Configure permissions:
    • Model-level access (per content type)
    • Stage-level permissions (draft, published, etc.)
    • Locale-specific access
    • API token permissions
    • Asset management rights
  5. Save and assign to team members

Permission Granularity

Available permission levels:

  • Read: View content and models
  • Create: Add new content entries
  • Update: Modify existing content
  • Delete: Remove content entries
  • Publish: Move content between stages
  • Unpublish: Revert published content

Permissions can be set per:

  • Content model
  • Content stage
  • Locale
  • Asset folder

Project and Environment Management

Hygraph organizes work into projects and environments:

Projects

Each project contains:

  • Content models and data
  • Team members and permissions
  • API endpoints and tokens
  • Webhooks and integrations
  • Billing configuration

Environments

Environments allow:

  • Separate development, staging, production setups
  • Different data sets per environment
  • Independent API endpoints
  • Team-specific access control
  • Safe testing without affecting production

Content Stages

Built-in content workflow stages:

  • Draft: Work-in-progress content
  • Published: Live, publicly accessible content
  • Custom Stages: Additional workflow steps (Enterprise)

API Token Management

Hygraph uses Permanent Auth Tokens for programmatic access:

Token Types

Permanent Auth Tokens (PAT):

  • Long-lived authentication tokens
  • Used for all API requests
  • Configurable permissions and scopes
  • Can be restricted to specific environments
  • Support IP whitelisting (Enterprise)

Managing API Tokens

To create and manage tokens:

  1. Navigate to Settings > API Access
  2. Click Create Token
  3. Configure token settings:
    • Name and description
    • Environment (specific or all)
    • Permissions (read, mutation, etc.)
    • Expiration (optional)
    • IP whitelist (Enterprise)
  4. Copy token immediately (shown only once)
  5. Store securely in environment variables

Token Permissions

Granular token permissions:

  • Read: Query content via GraphQL
  • Mutations: Create, update, delete content
  • Assets: Upload and manage files
  • Publish: Move content between stages
  • Management API: Modify models and schema

API Token Security

Best practices:

  1. Never Commit Tokens: Don't include in version control
  2. Use Environment Variables: Store in .env files or secret managers
  3. Separate Environments: Different tokens for dev/staging/production
  4. Minimal Permissions: Grant only required scopes
  5. Rotate Regularly: Change tokens every 90 days
  6. Monitor Usage: Review API analytics for unusual activity
  7. Revoke Unused: Delete old or unnecessary tokens
  8. IP Whitelisting: Restrict token usage to known IPs (Enterprise)

Adding and Inviting Team Members

Inviting Users

To add team members:

  1. Navigate to Settings > Team Members
  2. Click Invite Member
  3. Enter email address
  4. Select role from dropdown
  5. Configure permissions (if using custom roles)
  6. Send invitation

The invitee receives an email to:

  • Create a Hygraph account (if new)
  • Accept the project invitation
  • Access the shared project

Team Member Limits

User limits by plan:

  • Community Plan: 1 user
  • Professional Plan: Up to 5 users
  • Scale Plan: Up to 10 users
  • Enterprise Plan: Unlimited users

Removing Team Members

To remove a user:

  1. Go to Settings > Team Members
  2. Find the user to remove
  3. Click Remove or delete icon
  4. Confirm removal

Removed users lose immediate access. Their created content remains in the project.

Webhooks and Integrations

Hygraph supports webhooks for real-time event notifications:

Creating Webhooks

  1. Navigate to Settings > Webhooks
  2. Click Add Webhook
  3. Configure webhook:
    • Name and description
    • Trigger URL (your endpoint)
    • Events to trigger on
    • Content stages to monitor
    • HTTP headers and authentication
  4. Test webhook delivery
  5. Save and activate

Webhook Events

Available trigger events:

  • Content published
  • Content unpublished
  • Content created
  • Content updated
  • Content deleted
  • Asset uploaded
  • Asset updated
  • Asset deleted

Webhook Security

  • Use HTTPS endpoints only
  • Implement signature verification
  • Validate webhook payloads
  • Monitor delivery logs
  • Implement retry logic
  • Rate limit webhook endpoints

Content Localization

Hygraph provides robust multi-language support:

Localization Features

  • Create content in multiple locales
  • Locale-specific content fields
  • Fallback locale configuration
  • Automatic locale detection
  • GraphQL query locale filtering

Managing Translators

Assign permissions per locale:

  • Restrict contributors to specific languages
  • Review translations before publishing
  • Track translation completion status
  • Use localization workflows

GraphQL API Features

Hygraph's GraphQL-native approach offers:

GraphQL Advantages

  • Query multiple content types in one request
  • Precise field selection
  • Nested relationship queries
  • Real-time subscriptions (Enterprise)
  • Content federation capabilities
  • Automatic API documentation

GraphQL Playground

Interactive API explorer:

  • Test queries and mutations
  • View schema documentation
  • Inspect query performance
  • Generate code snippets
  • Debug API requests

Single Sign-On (SSO)

Enterprise plans support SSO:

Supported Providers

  • SAML 2.0
  • OAuth 2.0
  • Okta
  • Azure Active Directory
  • Google Workspace
  • Custom identity providers

SSO Configuration

  1. Contact Hygraph support to enable SSO
  2. Provide identity provider metadata
  3. Configure SAML or OAuth settings
  4. Map user attributes
  5. Test authentication flow
  6. Enable SSO enforcement

SSO Benefits

  • Centralized authentication
  • Automatic user provisioning
  • Enhanced security compliance
  • Reduced password management
  • Multi-factor authentication enforcement

Security Best Practices

Access Control

  1. Use Appropriate Roles: Assign least privileged role necessary
  2. Limit Owners: Only 1-2 project owners
  3. Regular Audits: Review team members quarterly
  4. Remove Inactive Users: Delete departed team members promptly
  5. Custom Roles: Use fine-grained permissions for specific needs

API Security

  1. Protect Tokens: Never expose in client-side code
  2. Environment Variables: Store securely
  3. Minimal Scopes: Grant only required permissions
  4. Token Rotation: Change tokens every 90 days
  5. IP Whitelisting: Restrict to known addresses (Enterprise)
  6. Monitor Usage: Set alerts for unusual API activity

Content Security

  1. Stage Workflows: Use draft/published stages
  2. Version Control: Enable content versioning
  3. Audit Logs: Review content changes regularly
  4. Backup Strategy: Regular content exports
  5. Disaster Recovery: Test recovery procedures

Common Issues and Solutions

Issue: API Token Not Working

Solution:

  • Verify token hasn't been deleted or revoked
  • Check token permissions/scopes
  • Ensure correct GraphQL endpoint URL
  • Verify environment matches token configuration
  • Check for API rate limiting

Issue: User Cannot Access Content

Solution:

  • Verify user role has appropriate permissions
  • Check stage-level permissions
  • Ensure user invitation was accepted
  • Review custom role configuration
  • Verify locale-specific permissions

Issue: Webhook Not Triggering

Solution:

  • Verify webhook URL is publicly accessible
  • Check webhook is enabled
  • Review event configuration
  • Ensure endpoint returns 200 status
  • Check delivery logs in Hygraph dashboard

Issue: GraphQL Query Errors

Solution:

  • Verify token has read permissions
  • Check GraphQL syntax
  • Ensure queried fields exist in schema
  • Review content stage in query
  • Check API rate limits

Issue: Cannot Publish Content

Solution:

  • Verify user has publish permissions
  • Check required fields are filled
  • Ensure content validation rules pass
  • Review stage workflow configuration
  • Check for conflicting content locks

Analytics Tool Access

Google Analytics 4

Manage GA4 access in Admin > Account/Property Access Management:

  • Administrator: Full control over account settings and users
  • Editor: Can modify configurations and settings
  • Analyst: Can create reports and audiences, no configuration changes
  • Viewer: Read-only access to reports and data

Since Hygraph is headless:

  • Implement GA4 tracking in your frontend application
  • Use Hygraph webhooks to trigger analytics events
  • Track content performance through application analytics

Google Tag Manager

Manage GTM access in Admin > User Management:

  • Administrator: Full control over container and users
  • Publish: Can publish container changes to production
  • Approve: Can approve changes but not publish
  • Edit: Can edit tags and triggers but cannot approve or publish
  • Read: View-only access to container configuration

Implement GTM:

  • Add container code to your application
  • Track Hygraph content views and interactions
  • Use custom events for content engagement

Meta Business Manager

Manage access in Business Settings > People:

  • Admin: Full control over business settings and assets
  • Employee: Limited access based on assigned assets and permissions

Best Practices

  1. Use Custom Roles: Create fine-grained permissions for your team structure
  2. Protect API Tokens: Never commit to version control or expose client-side
  3. Separate Environments: Use different projects/environments for dev/staging/production
  4. Enable Audit Logs: Track all user and content changes
  5. Implement Webhooks: Real-time content synchronization
  6. Version Control Schema: Export and track content model changes
  7. Regular Token Rotation: Change API tokens every 90 days
  8. Monitor API Usage: Review analytics for performance and security
  9. Document Permissions: Maintain clear records of access policies
  10. Test in Development: Always test permission changes in non-production

Additional Resources

返回顶部