GraphCMS (now Hygraph) Authentication: API Access & Security

Authentication overview

GraphCMS (now Hygraph) utilizes an authentication system designed to secure access to its GraphQL APIs. This system ensures that only authorized applications and users can interact with content, manage schemas, and publish data. The core mechanism for programmatic access relies on Permanent Auth Tokens (PATs), which are long-lived credentials assigned specific permissions within a project. These tokens are essential for integrating GraphCMS (now Hygraph) with various frontends, backend services, and automation tools.

Authentication in GraphCMS (now Hygraph) is integrated with its Role-Based Access Control (RBAC) system. Each token can be configured with precise permissions, limiting its scope to specific content models, stages (e.g., draft, published), and operations (e.g., read, create, update, delete). This granular control is vital for implementing the principle of least privilege, where credentials are only granted the minimum necessary access to perform their intended function. For instance, a token used by a public-facing website might only have read access to published content, while a build process token might require read/write access to draft content during development cycles. Hygraph provides comprehensive documentation on API authentication and tokens to guide developers through the setup process.

Supported authentication methods

GraphCMS (now Hygraph) primarily supports Permanent Auth Tokens (PATs) for API authentication. While the platform itself manages user logins via email/password or OAuth providers for dashboard access, programmatic API interactions rely on these tokens.

The following table outlines the primary authentication method:

Permanent Auth Tokens (PATs)

Permanent Auth Tokens are unique strings generated within the GraphCMS (now Hygraph) project dashboard. They act as bearer tokens, meaning that possession of the token is sufficient to grant access to the associated permissions. When making an API request, the PAT is included in the Authorization header as a Bearer token. The permissions assigned to a PAT determine which GraphQL operations (queries, mutations) and which content models it can access. Tokens can be configured for:

• Content API access: For querying and mutating content.
• Management API access: For programmatic schema changes, asset management, and other administrative tasks.
• Specific stages: Limiting access to 'DRAFT' or 'PUBLISHED' content.
• Specific content models: Restricting operations to particular types of content (e.g., 'Article', 'Product').

The official Hygraph documentation provides detailed guidance on creating and managing Permanent Auth Tokens.

Getting your credentials

To obtain a Permanent Auth Token for GraphCMS (now Hygraph), follow these steps within your project dashboard:

1. Log in to your Hygraph project: Access your project dashboard at the Hygraph homepage.
2. Navigate to Project Settings: In the left sidebar, locate and click on 'Project Settings'.
3. Access API Access: Within 'Project Settings', find the 'API Access' section.
4. Create a new Permanent Auth Token: Click on the 'Permanent Auth Tokens' tab and then click the 'Create Token' button.
5. Configure Token Permissions:
   • Name: Provide a descriptive name for your token (e.g., 'Frontend App Token', 'Build Process Token').
   • Environment: Select the environment (e.g., 'Production', 'Development') the token will be used in.
   • API: Choose 'Content API' for content operations or 'Management API' for administrative tasks.
   • Permissions: Carefully define the permissions. This is where you specify which content models, stages, and operations (read, create, update, delete) the token can perform. Apply the principle of least privilege. For example, a token for a public website might only need READ access on PUBLISHED content for specific models.
6. Generate Token: After configuring permissions, click 'Create' or 'Generate Token'. The token string will be displayed once. Copy this token immediately, as it will not be shown again for security reasons. If you lose it, you will need to revoke it and create a new one.

For detailed, step-by-step instructions, refer to the Hygraph Permanent Auth Tokens documentation.

Authenticated request example

Once you have your Permanent Auth Token, you can include it in your GraphQL API requests. Here's an example using JavaScript with fetch:

const GRAPHQL_ENDPOINT = 'YOUR_HYGRAPH_API_ENDPOINT'; // e.g., https://api-us-east-1.hygraph.com/v2/YOUR_PROJECT_ID/master
const PERMANENT_AUTH_TOKEN = 'YOUR_PERMANENT_AUTH_TOKEN';

async function fetchPublishedPosts() {
  const query = `
    query MyPosts {
      posts(where: { status: PUBLISHED }) {
        id
        title
        slug
      }
    }
  `;

  try {
    const response = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${PERMANENT_AUTH_TOKEN}`,
      },
      body: JSON.stringify({ query }),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Published Posts:', data.data.posts);
  } catch (error) {
    console.error('Error fetching posts:', error);
  }
}

fetchPublishedPosts();

In this example:

• GRAPHQL_ENDPOINT: This is your specific Hygraph project API endpoint, which can be found in the 'API Access' section of your project settings.
• PERMANENT_AUTH_TOKEN: Replace this with the actual token you generated.
• The Authorization header is set to Bearer YOUR_PERMANENT_AUTH_TOKEN. This is the standard way to pass a bearer token in an HTTP request, as detailed in RFC 6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage.

For more complex scenarios, such as using specific GraphQL clients or different programming languages, consult the Hygraph developer documentation for relevant SDKs and examples.

Security best practices

Securing your GraphCMS (now Hygraph) API access involves several critical practices:

• Principle of Least Privilege: Always grant the minimum necessary permissions to each Permanent Auth Token. If a token only needs to read published blog posts, do not give it write access or access to sensitive content models. Regularly review and adjust token permissions as project requirements evolve.
• Secure Storage: Never hardcode Permanent Auth Tokens directly into client-side code (e.g., JavaScript in a browser). For server-side applications, store tokens in environment variables or a secure secret management system (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). For client-side applications that need to access content, consider using a proxy server or an API gateway to manage token access, or if direct client-side access is unavoidable, ensure the token has extremely limited read-only permissions and is tied to specific content.
• Token Rotation and Expiration: While Permanent Auth Tokens are long-lived, it is a good practice to periodically rotate them, especially for critical integrations. If a token is compromised, revoke it immediately and generate a new one. GraphCMS (now Hygraph) allows you to revoke tokens at any time from the project dashboard.
• Environment-Specific Tokens: Use separate tokens for different environments (development, staging, production). This prevents a compromise in a development environment from affecting your production content.
• HTTPS/TLS Enforcement: All communication with GraphCMS (now Hygraph) APIs should occur over HTTPS (TLS). This encrypts data in transit, protecting your tokens and content from eavesdropping. GraphCMS (now Hygraph) enforces HTTPS by default.
• Monitoring and Auditing: Regularly monitor your API logs for unusual activity or unauthorized access attempts. While GraphCMS (now Hygraph) provides internal logging, integrating with external monitoring tools can offer enhanced visibility.
• Restrict Dashboard Access: Limit who has access to the GraphCMS (now Hygraph) project dashboard, as this is where tokens are generated and managed. Utilize strong, unique passwords and enable multi-factor authentication (MFA) for all user accounts.
• Understand API Endpoints: Be aware of the different API endpoints (e.g., Content API, Management API) and ensure your tokens are configured for the correct one, with appropriate permissions. The Management API, for instance, has broader capabilities and should be secured with extra vigilance.

Adhering to these best practices helps maintain the security and integrity of your content infrastructure powered by GraphCMS (now Hygraph).