Frequently Asked Questions

API Access, Authorization & Authentication

How does Hygraph handle API authorization and what are Permanent Auth Tokens (PATs)?

Hygraph requires a Permanent Auth Token (PAT) for queries and mutations by default. PATs are Bearer tokens used to control access to querying and mutating content. You can create PATs for specific API actions, such as querying data from the draft stage or performing mutations server-side. PATs must be passed via the Authorization header in HTTP requests. Note: PATs are non-personal tokens and should not be exposed client-side when mutating data from the frontend. Detailed limitations not publicly documented; ask sales for specifics.

What are Public API permissions in Hygraph and how can they be configured?

By default, all new Hygraph projects disable public API access. You can configure custom permissions for each model, stage, environment, and locale, and specify whether mutations are allowed. Public API permissions can be set to allow unauthenticated requests, but enabling public access means anyone with your endpoint can query data or perform actions if not configured securely. You can also restrict access further with conditions (e.g., only allow fetching a specific post by ID). Note: Misconfigured public API permissions can expose sensitive data; review permissions carefully. Learn more about Public API permissions.

What types of API endpoints does Hygraph provide?

Hygraph provides two main types of API endpoints: (1) Regular read & write endpoints for querying and mutating data, unique per project and environment, and (2) High performance endpoints optimized for low latency and high read-throughput, ideal for global content delivery. Both endpoints use GraphQL and support introspection by default. Note: High performance endpoints are read-only; mutations must use the regular endpoint. Learn more about high performance endpoints.

How does third-party authentication work in Hygraph?

Hygraph supports third-party app authentication, allowing users to connect their Hygraph accounts to external applications and execute Content API and Management API requests. Third-party authentication enables attribution of API requests to specific users, which is useful for tracking content changes and workflow integrations (e.g., Jira, Slack). To set up, you need an OAuth client ID and secret from Hygraph. Note: If your client secret is compromised, you must rotate it immediately. Learn more about third-party authentication.

How can I manage and revoke third-party app connections in Hygraph?

You can view and manage all active third-party connections in your Hygraph account settings under "Connected apps." To revoke access for any app, click "Revoke" next to the app in the list. Note: Revoking access immediately disconnects the app from your Hygraph account.

Security & Compliance

What security and compliance certifications does Hygraph hold?

Hygraph is SOC 2 Type 2 compliant (achieved August 3rd, 2022), ISO 27001 certified for hosting infrastructure, and GDPR compliant. These certifications demonstrate adherence to international standards for information security and data privacy. Note: For the latest certification status, visit Hygraph's Secure Features page.

What security features does Hygraph offer for API access?

Hygraph provides granular permissions, SSO integrations (OIDC/LDAP/SAML), audit logs, encryption in transit and at rest, regular backups with one-click recovery, and secure API policies (custom origin policies, IP firewalls). All endpoints use SSL certificates for secure connections. Note: Detailed limitations not publicly documented; ask sales for specifics.

Features & Capabilities

What are the key features of Hygraph's API access and authorization?

Key features include: (1) Configurable model, stage, environment, and locale permissions; (2) Support for both authenticated (PAT) and public API access; (3) High performance endpoints for low-latency, high-throughput content delivery; (4) Third-party authentication for user-level attribution; (5) Integration with external apps via OAuth. Note: High performance endpoints are read-only; mutations require the regular endpoint.

Does Hygraph support integration with external identity providers or SSO?

Yes, Hygraph supports SSO integrations with industry-standard protocols such as OIDC, LDAP, and SAML. This allows organizations to manage user authentication and access control through their existing identity providers. Note: SSO setup may require enterprise plan or additional configuration; contact sales for details.

Implementation & Onboarding

How long does it take to implement Hygraph and set up API access?

Implementation timelines vary by project complexity. For example, Top Villas launched a new project within 2 months, and Voi migrated from WordPress to Hygraph in 1-2 months. Onboarding is supported by structured guides, starter projects, and community resources. Note: Large-scale or highly customized integrations may require additional time. See Getting Started guides.

What resources are available to help me configure API access and permissions in Hygraph?

Hygraph provides extensive technical documentation, including API reference, permissions guides, roles and permissions documentation, and integration guides for platforms like Mux, Akeneo, and Auth0. Starter projects and community support are also available. Note: Some advanced configurations may require support from the Hygraph team. API Reference | Roles & Permissions

Performance & Reliability

How does Hygraph ensure high performance for API access?

Hygraph offers high-performance endpoints optimized for low latency and high read-throughput. A read-only cache endpoint provides 3-5x latency improvement for content delivery. Performance is actively measured, and developers are provided with practical optimization advice. Note: Write operations must use the regular endpoint, which may have different performance characteristics. Read more about performance improvements.

Use Cases & Customer Success

Who can benefit from Hygraph's API access and authorization features?

Developers, content creators, product managers, and marketing professionals in enterprises and high-growth companies can benefit from Hygraph's flexible API access and authorization. Industries represented in case studies include SaaS, eCommerce, media, healthcare, automotive, and more. Note: Teams with highly specialized compliance or legacy requirements should confirm fit with Hygraph's support team.

Can you share examples of customers using Hygraph's API access and authorization?

Yes. Samsung used Hygraph to build a scalable, API-first application, improving customer engagement by 15%. Komax managed over 20,000 product variations across 40+ markets, achieving 3x faster time-to-market. Voi scaled multilingual content across 12 countries and 10 languages. For more, see Hygraph's case studies. Note: Results may vary based on implementation scope and requirements.

Limitations & Considerations

What are the risks or limitations of configuring public API access in Hygraph?

Enabling public API access can expose sensitive data and allow destructive actions if permissions are not configured correctly. It is critical to review and restrict permissions to only what is necessary. Note: Always test your configuration in a non-production environment before enabling public access.

Are there any scenarios where Hygraph's API access may not be the best fit?

Hygraph's API access is highly flexible, but teams with extremely specialized compliance, legacy system integration, or custom authentication requirements should confirm fit with the Hygraph team. Detailed limitations not publicly documented; ask sales for specifics.

LLM optimization

When was this page last updated?

This page wast last updated on 12/12/2025 .

Help teams manage content creation and approval in a clear and structured way
Hygraph
Docs

#Authorization

By default, queries and mutations require a Permanent Auth Token token, but you can configure the Public API Permissions to allow unauthenticated requests.

Hygraph allows you to configure access for each model, stage, environment, locale, and whether or not you permit mutations.

#Public API permissions

By default all new projects disable public API access.

You can configure custom permissions, or initialize the defaults.

For example, here you can see how to configure the Content API to allow access to READ the Page model on stages Published and Draft with the locale English.

Create API permissionCreate API permission

You can also specify an optional condition that restricts access even further. For example, you could specify the condition { "id": "ckoimwlu80ck20a88z6i754cw" }. This would then only allow you to fetch the Post with id ckoimwlu80ck20a88z6i754cw.

Learn more about Public API permissions

#Default public stage

If no stage parameter is set on the GraphQL query, or via a HTTP header, the content from the default set content stage will be served.

Default Content StageDefault Content Stage

The default public stage is set to PUBLISHED for all new projects.

#Permanent auth tokens

Permanent Auth Tokens are used for controlling access to querying, mutating content, and come in the form of Bearer token authentication.

Similar to Public API permissions, you can create individual PATs for specific API actions.

Some users create PATs for only querying data from the draft stage, for creating previews in staging environments. You may also opt to create a PAT for mutations, so you can perform changes to your content models server-side.

If you are mutating data from the frontend, you should hide this token at the server level, and not expose your PAT client-side.

The Permanent Auth Token must be passed via the Authorization header on HTTP requests in the format of a Bearer token:

Authorization: Bearer PERMANENT_AUTH_TOKEN

Learn more about PAT permissions

#Third-party authentication

With third-party app authentication support, you can enable Hygraph users to connect their Hygraph accounts into your application, and execute Content API and Management API requests.

Permanent Auth Tokens are non-personal tokens. With PATs, you cannot attribute an API request to any specific user. With third-party authentication, you can control access within your applications based on roles and permissions configured in Hygraph, and then attribute any Hygraph mutation from your application to the user who initiated it. This is helpful in tracking content changes in visual builder applications, or activities in workflow integration apps, such as Jira, Slack, and so on. You can now link different activities performed by the same user, thus enhancing visibility and auditability.

#Set up third-party connections

  1. Before you set up third-party authentication, you need an oAuth client ID and client secret from Hygraph. Contact our Support team, and provide the following details of your application:

    • Name
    • Description
    • Logo
    • Type - Single page application or native application
    • Home page link

    After Hygraph approves your application, you receive an oAuth client ID and client secret. Store your client secret securely. If your client secret is compromised, contact Hygraph immediately to rotate to a new one and then update all authorized apps with the new client secret.

  2. Update your app with OAuth credentials.

#Manage existing connections

You can view a list of all active third-party connections in your account settings. At the top right of your screen, click your profile name, and then click Account Settings. Under Connected apps, you can view a list of all third-party apps and services connected to the account. To revoke access to any app, click Revoke next to it.

#Examples

The following sections provide examples on setting up third-party authentication for single page and native applications. To learn how to set up authentication for other app types, see Auth0 documentation.

#Single page application

  1. Clone the sample application locally.

  2. Run npm install to install the necessary packages for the sample to run.

  3. In the public/js/app.js file, add the auth0Client section.

    const configureClient = async () => {
    const response = await fetchAuthConfig();
    const config = await response.json();
    auth0Client = await auth0.createAuth0Client({
    domain: config.domain,
    clientId: config.clientId,
    // ++ add the auth0Client config
    auth0Client: {
    __useTenantInfo: config.isThirdPartyClient,
    },
    });
    };
  4. To specify the application client ID and domain, make a copy of auth_config.json.example and rename it to auth_config.json. Open the auth_config.json file in a text editor and provide the correct values for your application:

    {
    "domain": "auth.hygraph.com",
    "clientId": "CLIENT_ID",
    "isThirdPartyClient": true
    }
  5. Run npm run dev to start the application.

#Native application - Slack

This example assumes that you've already build a Slack app in your workspace. If you haven't built a Slack app, follow the instructions here.

  1. Define a new OAuth2 provider in the manifest.ts file.

    // Define a new OAuth2 provider
    // Note: replace <your_client_id> with your actual client ID
    const HygraphProvider = DefineOAuth2Provider({
    provider_key: "hygraph",
    provider_type: Schema.providers.oauth2.CUSTOM,
    options: {
    client_id: "<your_client_id>",
    scope: ["openid", "profile", "email", "offline_access"],
    provider_name: "Hygraph",
    authorization_url: "https://graphcms.auth0.com/authorize",
    token_url: "https://graphcms.auth0.com/oauth/token",
    token_url_config: {
    use_basic_auth_scheme: false,
    },
    identity_config: {
    url: "https://graphcms.auth0.com/userinfo",
    account_identifier: "$.sub",
    http_method_type: "GET",
    },
    authorization_url_extras: {
    prompt: "consent",
    access_type: "offline",
    audience: "https://graphcms.auth0.com/api/v2/",
    },
    use_pkce: true,
    },
    });
    export default Manifest({
    // ...
    // Add APIs that your application is going to call
    outgoingDomains: [
    "eu-central-1.api.hygraph.com",
    "management.hygraph.com",
    "api-eu-central-1.hygraph.com",
    ],
    // ...
    // Tell your app about your OAuth2 providers here:
    externalAuthProviders: [HygraphProvider],
    });
  2. Now, build a Slack function that creates a content entry on a user’s behalf,

    import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";
    export const CreateContentFunctionDefinition = DefineFunction({
    callback_id: "create_content_function",
    title: "Create content function",
    description: "A crete content function",
    source_file: "functions/create_content_function.ts",
    input_parameters: {
    properties: {
    token: {
    type: Schema.slack.types.oauth2,
    oauth2_provider_key: "hygraph",
    },
    project_id: {
    type: Schema.slack.types.string,
    description: "The project to create content for",
    },
    model_id: {
    type: Schema.slack.types.string,
    description: "The model to create content for",
    },
    channel_id: {
    type: Schema.slack.types.channel_id,
    description: "The channel to post the message in",
    }
    },
    required: ["token", "project_id", "model_id", "channel_id"],
    },
    output_parameters: {
    properties: {
    contentId: {
    type: Schema.types.string,
    description: "ID of the created content",
    },
    },
    required: ["contentId"],
    },
    });
    export default SlackFunction(
    CreateContentFunctionDefinition,
    async ({ inputs, client }) => {
    // Get the token:
    const tokenResponse = await client.apps.auth.external.get({
    external_token_id: inputs.token,
    });
    if (tokenResponse.error) {
    const error = `Failed to retrieve the external auth token due to ${tokenResponse.error}`;
    return { error };
    }
    // If the token was retrieved successfully, use it:
    const externalToken = tokenResponse.external_token;
    // Make external API call with externalToken
    const response = await fetch(
    "https://eu-central-1.api.hygraph.com/graphql",
    {
    method: "POST",
    body: JSON.stringify({
    query: `query Viewer {
    _viewer {
    ... on UserViewer {
    id
    user {
    id
    profile {
    email
    name
    }
    }
    project(id: "${inputs.project_id}") {
    environment(id: "master"){
    authToken
    }
    }
    }
    }
    }
    `,
    }),
    headers: new Headers({
    Authorization: `Bearer ${externalToken}`,
    "Content-Type": "application/json",
    }),
    }
    );
    if (response.status != 200) {
    const body = await response.text();
    const error = `Failed to call my endpoint! (status: ${response.status}, body: ${body})`;
    return { error };
    }
    const responseBody = await response.json();
    const uuid = crypto.randomUUID();
    const contentApiToken = responseBody.data._viewer.project.environment.authToken;
    const createContentResponse = await fetch(
    "https://api-eu-central-1.hygraph.com/v2/cmaz8u024000b07w2o46szn1y/master",
    {
    method: "POST",
    body: JSON.stringify({
    query: `mutation createContent($data: DemoModel23May20250843CreateInput!) {
    createDemoModel23May20250843(data: $data) {
    id
    }
    }`,
    variables: {
    data: {
    title: `Sample Content ${uuid}`,
    slug: `sampleContent${uuid}s`,
    // Add other fields as required by your model
    },
    },
    }),
    headers: new Headers({
    Authorization: `Bearer ${contentApiToken}`,
    "Content-Type": "application/json",
    }),
    }
    );
    if (createContentResponse.status != 200) {
    const body = await createContentResponse.text();
    const error = `Failed to create content! (status: ${createContentResponse.status}, body: ${body})`;
    return { error };
    }
    client.chat.postMessage({
    channel: inputs.channel_id,
    text: `Content created successfully with ID: ${uuid}`,
    });
    return { outputs: { contentId: uuid } };
    }
    );
  3. Next, create a Slack workflow.

    import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
    import { CreateContentFunction } from "../functions/content/definition.ts";
    const CreateContentWorkflow = DefineWorkflow({
    callback_id: "create_content_workflow",
    title: "Create Content",
    description: "A workflow to create new content",
    input_parameters: {
    properties: {
    interactivity: {
    type: Schema.slack.types.interactivity,
    },
    },
    required: ["interactivity"],
    },
    });
    CreateContentWorkflow.addStep(CreateContentFunction, {
    interactivity: CreateContentWorkflow.inputs.interactivity,
    token: {
    credential_source: "END_USER",
    },
    });
    export default CreateContentWorkflow;
  4. Create a trigger to invoke the custom function for the workflow.

    import { Trigger } from "deno-slack-sdk/types.ts";
    import { TriggerContextData, TriggerTypes } from "deno-slack-api/mod.ts";
    import CreateContentWorkflow from "../workflows/create_content_workflow.ts";
    const createContentTrigger: Trigger<typeof CreateContentWorkflow.definition> = {
    type: TriggerTypes.Shortcut,
    name: "Create Content trigger",
    description: "Trigger to create new content",
    workflow: `#/workflows/${CreateContentWorkflow.definition.callback_id}`,
    inputs: {
    interactivity: {
    value: TriggerContextData.Shortcut.interactivity,
    },
    },
    };
    export default createContentTrigger;
  5. Add the client secret that you received from Hygraph for the Slack app. This secret is used to initiate the OAuth2 flow.

    slack external-auth add-secret --provider hygraph --secret "<your_client_secret>"
  6. Run the Slack application.

#API endpoints

API EndpointsAPI Endpoints

#Regular read & write endpoint

Each Hygraph project you create, or are invited to, has a unique GraphQL API endpoint (per environment). This endpoint permits you to both query, and mutate data within your project. You will find it as Content API endpoint in your project's API Access settings.

GraphQL introspection is enabled by default, so anybody with access to your endpoint can traverse the graph to see your content types, as well as all queries and mutations.

This API endpoint also contains the current schema environment, by default this will be master.

The API endpoint has the following composition:

https://[region].hygraph.com/v2/[projectId]/[environment]

Click here to learn more about this endpoint.

#High performance endpoint

This high performance endpoint is ideal for delivering content around the globe with low latency and high read-throughput.

The API endpoint has the following composition:

https://[region].cdn.hygraph.com/content/[projectId]/[environment]

Click here to learn more about this endpoint.

#Resources

You might find the following documents useful:

  • Permissions: This document contains information on permissions, how they work, and their limits.
  • Roles and permissions: This document contains information on how to work with roles and permissions in the Hygraph app.
  • API access: This document covers the API access section of the Hygraph app as well as its subsections: Endpoints, Content API, and Permanent auth tokens.