Adding & Removing Users on GraphCMS

Adding & Removing Users on GraphCMS — setup, configuration, and best practices for Graphcms.

GraphCMS (now rebranded as Hygraph) is a headless GraphQL-native CMS. Team members are managed per-project through the Hygraph dashboard at app.hygraph.com and the Hygraph Management API. All user operations use GraphQL mutations.

Adding Users via the Dashboard

Inviting Team Members

Log in to app.hygraph.com
Select the target project
Click Project Settings (gear icon in the sidebar)
Navigate to Access > Team Members
Click Invite Member
Enter the invitee's email address
Select a role:
- Owner -- Full access including billing, project deletion, and team management
- Admin -- Full access to content, schema, and settings; cannot manage billing
- Developer -- Schema management, webhooks, API playground, and content access
- Content Editor -- Create, edit, and publish content; no schema or settings access
- Viewer -- Read-only access to content; cannot edit or publish
Click Send Invite

The invited user receives an email to join the project. They must create a Hygraph account or log in with an existing one.

Plan-Based User Limits

Plan	Team Members
Community (Free)	3
Professional	10
Scale	25
Enterprise	Custom

Adding Users via the Management API (GraphQL)

Hygraph provides a Management API that uses GraphQL for all operations:

# Invite a team member via the Management API
mutation InviteTeamMember {
  sendInvite(
    data: {
      email: "jsmith@example.com"
      role: ContentEditor
    }
  ) {
    id
    email
    role
    status
  }
}

# Execute the mutation via curl
curl -X POST "https://management.hygraph.com/graphql" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { sendInvite(data: { email: \"jsmith@example.com\", role: ContentEditor }) { id email role status } }"
  }'

Using the Hygraph Management SDK

// Install: npm install @hygraph/management-sdk

const { Client } = require('@hygraph/management-sdk');

const client = new Client({
  authToken: process.env.HYGRAPH_MANAGEMENT_TOKEN,
  endpoint: 'https://management.hygraph.com/graphql',
});

// Invite a team member
async function inviteMember(email, role) {
  const result = await client.run({
    query: `
      mutation InviteMember($email: String!, $role: MemberRole!) {
        sendInvite(data: { email: $email, role: $role }) {
          id
          email
          role
          status
        }
      }
    `,
    variables: { email, role },
  });
  console.log(`Invited: ${email} as ${role}`, result);
}

// List all team members
async function listTeam() {
  const result = await client.run({
    query: `
      query TeamMembers {
        viewer {
          project {
            members {
              id
              email
              role
              createdAt
            }
            pendingInvites {
              id
              email
              role
              status
            }
          }
        }
      }
    `,
  });
  return result.viewer.project;
}

inviteMember('jsmith@example.com', 'ContentEditor');

Custom Roles (Enterprise)

Enterprise plans support custom roles with granular permissions:

# Create a custom role
mutation CreateCustomRole {
  createRole(
    data: {
      name: "Blog Editor"
      description: "Can manage blog posts and authors only"
      permissions: {
        content: {
          models: ["BlogPost", "Author"]
          actions: [READ, CREATE, UPDATE, PUBLISH]
        }
        asset: {
          actions: [READ, CREATE]
        }
      }
    }
  ) {
    id
    name
  }
}

Removing Users

Removing via the Dashboard

Go to Project Settings > Access > Team Members
Find the team member
Click the three-dot menu next to their name
Select Remove
Confirm the removal

Removing via the Management API

# Remove a team member
mutation RemoveMember {
  removeMember(where: { id: "MEMBER_ID" }) {
    id
    email
  }
}

curl -X POST "https://management.hygraph.com/graphql" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { removeMember(where: { id: \"MEMBER_ID\" }) { id email } }"
  }'

What Happens to Their Content

When you remove a Hygraph team member:

All content they created remains intact -- published, draft, and scheduled content is unaffected
Content delivered via the Content API and GraphQL endpoints continues without interruption
The createdBy and updatedBy system fields on content entries retain the user's reference
Assets (images, files) uploaded by the user remain in the asset library
The removed user immediately loses dashboard and API access to the project
Their Hygraph account continues to exist but is disconnected from your project
Webhooks configured by the user remain active

Revoking Pending Invitations

# Revoke a pending invitation
mutation RevokeInvite {
  revokeInvite(where: { id: "INVITE_ID" }) {
    id
    email
    status
  }
}

Bulk User Management

Bulk Invite Script

// bulk-invite.js -- Invite multiple users from a JSON file
const { Client } = require('@hygraph/management-sdk');

const client = new Client({
  authToken: process.env.HYGRAPH_MANAGEMENT_TOKEN,
  endpoint: 'https://management.hygraph.com/graphql',
});

const invites = [
  { email: 'alice@example.com', role: 'ContentEditor' },
  { email: 'bob@example.com', role: 'Developer' },
  { email: 'carol@example.com', role: 'Viewer' },
];

async function bulkInvite() {
  for (const invite of invites) {
    try {
      const result = await client.run({
        query: `
          mutation InviteMember($email: String!, $role: MemberRole!) {
            sendInvite(data: { email: $email, role: $role }) {
              id email status
            }
          }
        `,
        variables: invite,
      });
      console.log(`OK: ${invite.email} (${invite.role})`);
    } catch (err) {
      console.error(`FAIL: ${invite.email} -- ${err.message}`);
    }
  }
}

bulkInvite();

Audit Team Members

// audit-team.js -- Export team members to CSV
const { Client } = require('@hygraph/management-sdk');

const client = new Client({
  authToken: process.env.HYGRAPH_MANAGEMENT_TOKEN,
  endpoint: 'https://management.hygraph.com/graphql',
});

async function auditTeam() {
  const result = await client.run({
    query: `
      query {
        viewer {
          project {
            members { id email role createdAt }
            pendingInvites { id email role status createdAt }
          }
        }
      }
    `,
  });

  const { members, pendingInvites } = result.viewer.project;

  console.log('email,role,status,created');
  members.forEach(m => console.log(`${m.email},${m.role},active,${m.createdAt}`));
  pendingInvites.forEach(i => console.log(`${i.email},${i.role},${i.status},${i.createdAt}`));
}

auditTeam();

SSO and Enterprise Authentication

Available Authentication Methods

Email/password -- Standard Hygraph account login
GitHub OAuth -- Sign in with GitHub
Google OAuth -- Sign in with Google
SAML 2.0 -- Enterprise plans only (Okta, Azure AD, OneLogin, etc.)

Configuring SAML SSO (Enterprise)

Go to Project Settings > Access > SSO
Enable SAML Single Sign-On
Configure:
- Identity Provider SSO URL: Your IdP's login endpoint
- Identity Provider Entity ID: Your IdP's entity identifier
- X.509 Certificate: Paste the IdP's signing certificate
- Default Role: Role assigned to new SSO users
Copy the ACS URL and SP Entity ID and configure them in your IdP
Test with a non-admin user
Enable Enforce SSO to require all users to authenticate via SAML

SSO Auto-Provisioning

With SAML SSO and auto-provisioning enabled, new users are automatically added to the project on first login:

SSO Settings:
├── Auto-provisioning: Enabled
├── Default role: Content Editor
├── Domain restriction: @yourdomain.com only
└── Enforce SSO: Yes (blocks email/password login)

API Token Management

Hygraph uses Permanent Auth Tokens (PATs) and API endpoints that are separate from user accounts. When offboarding, also manage tokens:

# List all API tokens
query ListTokens {
  viewer {
    project {
      permanentAuthTokens {
        id
        name
        token
        createdAt
        permissions {
          model
          actions
        }
      }
    }
  }
}

# Delete a specific token
mutation DeleteToken {
  deletePermanentAuthToken(where: { id: "TOKEN_ID" }) {
    id
    name
  }
}

Offboarding Checklist

Remove the team member from Project Settings > Access > Team Members
Rotate API tokens -- Delete any PATs the departing user created and regenerate if needed
Review webhooks -- Check for webhooks the user configured that may point to their personal endpoints
Audit schema changes -- If the user had Developer or Admin access, review recent schema modifications
Check integrations -- Remove any connected services (Netlify, Vercel, etc.) using the departing user's credentials
Update SSO -- If using SAML, deactivate the user in your identity provider
Review content stages -- Ensure no content is stuck in a workflow stage assigned to the removed user
Transfer project ownership if the departing user is the project Owner