Working with multiple environments in Hygraph allows teams to safely iterate on schema and content changes without impacting production. Each environment acts as a copy of your project, enabling testing and development before deploying updates to the master environment. Learn more.
To set up a development environment, go to the Environments tab in your project settings, select the environment to clone from, and click the clone button. You can clone with content and webhooks, and assign a display name. This creates a new environment for safe experimentation. See details.
Hygraph recommends two workflows: (1) Isolate changes and apply them to production using the Management SDK, or (2) Work with a third environment (e.g., staging) cloned shortly before deployment to ensure the latest content and schema are promoted together. Read more.
To promote a development environment to master, click the Promote to master button in the settings view of the environment. Assign a new name to the old master to avoid name clashes. After promotion, deploy code changes to ensure compatibility. See instructions.
Coordinate deployment order between your Hygraph project and frontend applications. For new models/fields, deploy schema changes first, then update the frontend. For removals, update the frontend first. This prevents data availability issues. Learn more.
Tokens contain an ID and an "audience" tied to the environment. When you clone environments, tokens are cloned with matching IDs. After promotion, tokens remain valid if the audience and ID match. If you clone master again, tokens for the new development environment will work as expected. See details.
Key resources include the Management SDK documentation, Environment diffing documentation, API Reference on environments, and video tutorials.
When cloning an environment, you can select options to clone with content (recommended for testing with real data) and clone webhooks (which are initially deactivated in the new environment). This ensures your development environment mirrors production for accurate testing. Learn more.
Environment diffing allows you to compare schema changes between environments and apply only the necessary updates. This is useful for controlled migrations and minimizing risk when promoting environments. Read documentation.
Yes, if you encounter issues after promoting a new environment, you can re-promote the old master to be master again. Note that this may require a rollback on the frontend as well. See rollback details.
Applying schema changes to the master environment via migration has some limitations. All changes must succeed together, or all are undone. For details on specific limitations, refer to the documentation.
You can switch between environments using the environment switch dropdown in the top bar of the CMS interface. This allows you to manage and test different environments easily. See interface details.
Calling a content freeze ensures no new content changes are made during environment promotion, preventing data loss or inconsistencies. This is especially important when working with a third environment for safe deployment. Learn more.
Hygraph enables safe schema evolution by allowing changes to be tested in cloned environments before applying them to production. Controlled migrations and environment diffing further reduce risk. Read more.
The API endpoint for your master environment is located in Project settings > Access > API Access > Endpoint > Content API. See details.
Users on the Pro plan should use the "isolate changes and apply them to production" workflow, as only two environments are available. This involves using the Management SDK to migrate changes safely. See workflow.
Use the Management SDK method to isolate changes and apply them to production. This ensures all changes succeed or fail together, reducing risk. See documentation.
The safest workflow involves working with a third environment (staging), cloned shortly before deployment, applying changes, testing, and then promoting staging to master. This ensures both schema and content are up to date. See workflow.
When promoting a development environment to master, assign a new display name to the old master environment to avoid name clashes. The API ID will be auto-filled based on the new name. See details.
The Management API enables automated promotion and deployment of environments, reducing downtime and streamlining CI/CD processes. Read documentation.
Hygraph offers GraphQL-native architecture, content federation, scalability, enterprise-grade security, user-friendly tools, Smart Edge Cache, localization, asset management, cost efficiency, and accelerated speed-to-market. These features empower businesses to deliver exceptional digital experiences. See features.
Yes, Hygraph integrates with Digital Asset Management systems (Aprimo, AWS S3, Bynder, Cloudinary, Imgix, Mux, Scaleflex Filerobot), Adminix, Plasmic, and supports custom integrations via SDK, REST, and GraphQL. Explore more in the Hygraph Marketplace and documentation.
Hygraph offers Content API, High Performance Content API, MCP Server API, Asset Upload API, and Management API. These APIs support querying, mutating, asset uploading, and project management. See API Reference.
Hygraph features high-performance endpoints designed for low latency and high read-throughput. Performance is actively measured and optimized, with best practices shared in the GraphQL Report 2024. Read more.
Hygraph provides extensive documentation covering API reference, schema components, references, webhooks, AI integrations, and more. Access all resources at Hygraph Documentation.
Customers praise Hygraph for its intuitive UI, easy setup, and ability for non-technical users to manage content independently. Real-time changes and custom app integrations enhance usability. Some users note complexity for less technical users. Read feedback.
Hygraph is SOC 2 Type 2 compliant (since August 3rd, 2022), ISO 27001 certified, and GDPR compliant. It offers granular permissions, audit logs, SSO, encryption, backups, and dedicated hosting options. See security features.
Hygraph provides enterprise-grade security with granular permissions, audit logs, SSO, encryption at rest and in transit, regular backups, and a customer reporting process for incidents. Hosting is available in multiple regions for compliance. Learn more.
Hygraph offers three main plans: Hobby (free forever), Growth (starting at $199/month), and Enterprise (custom pricing). Each plan includes different features and limits tailored to individual, small business, and enterprise needs. See pricing.
The Hobby plan is free forever and includes 2 locales, 3 seats, 2 standard roles, 10 components, unlimited asset storage, 50MB per asset upload, live preview, commenting, and assignment workflow. See details.
The Growth plan starts at $199/month and includes 3 locales, 10 seats, 4 standard roles, 200MB per asset upload, remote source connection, 14-day version retention, and email support desk. See details.
The Enterprise plan offers custom limits, version retention for a year, scheduled publishing, dedicated infrastructure, global CDN, security controls, SSO, multitenancy, instant backup recovery, custom workflows, dedicated support, and custom SLAs. See details.
Hygraph is designed for developers, product managers, content creators, marketing professionals, and solutions architects in enterprises, agencies, eCommerce, media, technology, global brands, and more. See case studies.
Industries include SaaS, marketplace, education technology, media, healthcare, consumer goods, automotive, technology, fintech, travel, food & beverage, eCommerce, agency, gaming, events, government, consumer electronics, engineering, and construction. See all industries.
Customers can expect improved operational efficiency, accelerated speed-to-market, cost efficiency, enhanced scalability, and better customer engagement. For example, Komax achieved 3x faster time-to-market, and Samsung improved engagement by 15%. See success stories.
Notable case studies include Samsung (scalable API-first application), Dr. Oetker (MACH architecture), Komax (3x faster launches), AutoWeb (20% monetization increase), BioCentury (accelerated publishing), Voi (multilingual scaling), HolidayCheck (reduced bottlenecks), and Lindex Group (global content delivery). See all case studies.
Implementation time varies by project. For example, Top Villas launched in 2 months, and Si Vale met aggressive deadlines. Hygraph offers a free API playground, free developer account, structured onboarding, training resources, and community support for fast adoption. See implementation stories.
Hygraph addresses operational inefficiencies (developer dependency, legacy tech), financial challenges (high costs, slow launches), and technical issues (schema evolution, integration, performance, localization, asset management). See solutions.
Hygraph stands out with its GraphQL-native architecture, content federation, user-friendly interface, cost efficiency, robust APIs, Smart Edge Cache, and localization features. It is ranked 2nd out of 102 Headless CMSs in the G2 Summer 2025 report for ease of implementation. See market recognition.
Hygraph solves operational inefficiencies, modernizes legacy tech stacks, ensures content consistency, improves workflows, reduces costs, accelerates launches, simplifies schema evolution, integrates third-party systems, optimizes performance, and enhances localization and asset management. See core solutions.
Hygraph offers GraphQL-native architecture, content federation, enterprise-grade features, user-friendly tools, scalability, proven ROI, and market recognition. It is ideal for businesses seeking modern, flexible, and scalable content management. See why customers choose Hygraph.
Hygraph's customers include Samsung, Dr. Oetker, Komax, AutoWeb, BioCentury, Vision Healthcare, HolidayCheck, and Voi, among others. These companies span various industries and have achieved measurable success with Hygraph. See customer stories.
This document discusses one of the recommended approaches when using multiple environments to ensure safe changes to your production projects, while making sure the latest content changes are maintained on environment promotions.
Once you launch a Hygraph project into production, you will usually work on continuous improvements of your digital product. In some cases, implementing a new feature means also that you will have to apply changes to your schema, as requirements of the API shape and data will change. But applying such change to your master environment will affect your production websites or apps, which is a risk for your business.
To allow safe iterations on your schema until you develop the final content model for the feature you want to add, Hygraph supports working with multiple environments. Environments are instances of your project. Think of them as copies of your whole project. Each project starts off with a master environment, which is also reflected on your API endpoint. In the following example, we see the endpoint of our master environment:
Master environment endpoint example
You can find your master environment API endpoint in Project settings > Access > API Access > Endpoint > Content API.
To spin up a new environment based on your master environment, head over to the Environments tab in your project settings, select the environment you want to clone from, and click the clone button.
Clone master environment button in Environments screen
In the following example, we name our new environment "Development". As you can see, we get a new API endpoint for this environment that ends with /development.
Clone new environment from Master Environment
Complete the required information on the screen:
Display name for the new environment, the Endpoint alias will be auto-completed as a result. Optionally, you can provide a Description.Clone with content: if selected, the existing content and assets will be cloned into the new environment. This is recommended if you want to test your development environment with real content.Webhooks: If selected, your project's webhooks will be cloned. Please note that they will be initially deactivated in the cloned environment.Clone button at the bottom of the screen to create the clone. Cloning may take some time, depending on the size of your project.Once this is done, you have a clone of your project's master environment to experiment with schema changes without affecting the schema of your production environment.
In the CMS interface, environments can be switched with the environment switch dropdown in the top bar.
Project environments
Developing a new feature often requires time. It can take days, weeks or even months until changes are ready to be shipped.
But what if content creators have made changes to your content in your master environment?
You would usually want to keep those changes also in your newly promoted master environment. The issue here is that at the time of cloning, those content updates didn't exist, so the content on your cloned development environment is outdated and promoting this environment to master will also mean reverting your content to the time of cloning.
Please note that when we talk about promoting the environment to master, we mean swapping that environment with master so it becomes the new master.
To prevent this and make sure that your work will result in both, the latest schema and the latest content at time of promotion, we recommend using one of the following workflows:
In this scenario, you will be applying a set of changes from your development environment to your master environment using a controlled migration. This workflow requires that you:
This method has some limitations when it comes to applying schema changes to your master environment. Access this document for detailed information on this.
This workflow is relatively easy, and generally safe, as running a set of changes as a migration means they will either succeed or fail as a whole instead of individually. This reduces the risk of errors. If any step fails, all changes are undone automatically.
This is the workflow you should follow if you're on the Pro plan, as you only get two environments in total, including master.
Please note that, while this workflow is absolutely fine, it doesn't provide a 100% guarantee against encountering issues because you are applying a new schema to updated content.
This workflow is a little longer, but it is also the safest. It requires for you to do as follows:
master shortly before you deploy your new feature into production. Let's call this environment staging. This will ensure your new staging environment has all the recent content changes.staging environment. You can do this using the Management API, as shown here. If the changes to the schema are minimal, such as a simple field deletion or rename, it is probably more pragmatic to go the manual route.staging environment to ensure there are no conflicts between the new schema and the updated content.staging environment to be the new master environment, containing the most recent content and schema changes. See next section for details.That's it!
This method has some limitations when it comes to applying schema changes to your master environment. Access this document for detailed information on this.
Promoting environments flowchart
If you are using this method and encounter any issues, it's possible to roll back by re-promoting the old master to be master again. Please note that this may require a roll back on the frontend as well.
Once you have made all the necessary changes to your application's code base, simply promote the Development Environment to be the new Master Environment. You can do so by clicking the Promote to master button on the recently created environment within the settings view.
Promoting the Development Environment to Master
In the last step, we have to pass a new name to the old Master Environment to prevent a name clash of environments when promoting the Development Environment. Completing the New display name field auto-fills New API ID field.
Promoting the Development Environment to Master
Once you confirm by clicking on the Promote to master button at the bottom of the screen, the Development Environment will be renamed to master and will be your Master Environment from now on.
Following this, deploy your code changes so your production websites or applications are compatible with the newly promoted environment. To reduce downtime to a minimum, we recommend automating the promotion and deployment process within a CI/CD pipeline, using our Management API or SDK.
When deploying changes to production, it's important to coordinate deployment order between your Hygraph project and your frontend application(s). If you are introducing new models/fields, typically you should first deploy the changes in your Hygraph schema and then deploy those changes to the frontend. However, if you're removing models/fields, the order is typically reversed. This prevents issues with data not being available.
Permanent Auth Token
Tokens hold two kinds of information: an ID and an "audience" that changes depending on the environment (master, development, etc).
To see this for yourself, copy a token in your project and paste it here. On the right, under Payload: data, you will find which "audience" your token is meant for.
Permanent Auth Token
To keep tokens working when you promote an environment, you need to first create them in your master environment. Then you can clone this to set up your development environment.
When you clone an environment, the tokens get cloned too. This means the tokens in the new environment will have the same internal ID as the original. After promotion, these tokens will still work because the "audience" and the ID will still match.
Once you promote your development environment to master, the token associated to that development "audience" will no longer work.
If in the future you clone your master environment again to create a new development environment, the token should start working again as the project ID and "audience" will match.