Environments | Canopy Docs

Overview

Environments are the unit of access-control isolation inside an Application. Each Environment is a self-contained workspace with its own permissions, roles, hierarchy, API keys, OAuth clients, and webhooks, completely independent from sibling Environments in the same Application. Most teams use Environments to mirror their software development lifecycle (development, staging, production), but the system imposes no naming convention or count: you can run a single Environment per Application or many, with any names that match how your team works.

Access Control Context

Environment is the context for Access Control

When you select an Environment in the Console's workspace switcher, every page under Access Control (Overview, Hierarchy, Identities, Roles, Permissions, Integrations) re-scopes to that Environment's data.

Permissions in Development are not the same rows as permissions in Production

Identities and their role assignments aren't carried between Environments. Adding someone and granting them Manager in Development gives them no access in Production until you add and assign them there too

An API key minted in Development will fail to read Production data

This is what makes safe iteration possible. Reshape the hierarchy, add and rename permissions, hand out roles, and test invite flows inside Development, with zero risk of affecting Production. When the configuration is solid, push it across with the Promote action on the Application's environment card.

One deliberate exception: identities and role assignments are never copied across Environments. An identity is a single Account-level record, but it isn't automatically present in any Environment. You invite or add it to each Environment that needs it, and assignments are operational state you choose per env. A promote from Development to Production brings the permissions, roles, and hierarchy, but Production still has zero people in it until you add and assign them.

Moving Configuration Between Environments

There are four mechanisms for moving configuration from one Environment to another: three primitives plus one guided flow built on top. The rules are the same across all four.

How to find these actions

Open the Tenant → Applications page in the Developer Console.
Locate the Application whose Environment you want to act on.
On the Environment card, open the kebab menu (the three-dot icon in the card's top-right). You'll see Export Configuration, Import Configuration, and Promote Configuration to… alongside the other env actions.

What's copied, what isn't

Copied: permissions, roles, role-permission joins, the access model + hierarchy schema + nodes, the organizations container setting (never the organizations themselves), OAuth client configurations, webhook configurations

Never copied: identities, role assignments, API keys

Rotated: OAuth client secrets and webhook signing secrets are regenerated in the target Environment; the originals never travel. The new secrets are shown once in a New secrets dialog right after the clone, import, or promote, so copy them then. If you miss them, use the Rotate secret action on the OAuth client or webhook to mint a fresh one.

Even after a full clone, the target Environment starts with zero people and zero assignments. Those are operational state you choose deliberately per env.

Clone on create

When you create a new Environment, the Create Environment dialog has a Copy configuration from dropdown. Pick a source Environment and the backend seeds the new one with that source's full configuration. Use this when you're standing up a fresh Environment (e.g., spinning up a new qa env modeled on development) and want to start populated rather than empty.

Export configuration

The Export Configuration action downloads the Environment's full configuration as a JSON file named <account>-<app>-<env>-config-YYYY-MM-DD.json. The source Environment is unchanged, because export is read-only. Useful for offline review, version control, or handing the configuration off to another tool.

Import configuration

The Import Configuration action opens a file-upload dialog. Provide a Canopy-exported JSON file, confirm the replacement, and the backend overwrites the target Environment's configuration with the file's contents.

Import is replace-semantics, not merge: anything in the target that isn't in the file gets removed. Identities, role assignments, API keys, and secrets are left alone as always, but everything in the configuration scope (permissions, roles, hierarchy, OAuth/webhook configs) is fully overwritten.

Promote configuration to…

The Promote Configuration to… action is the one-click version of export-then-import. Pick a target Environment in the same Application, confirm, and the Console runs the export on the source and the import on the target in sequence. The same replace-semantics apply.

Promote runs as two network calls (export then import) and is not atomic across the pair. If the export fails, the source is untouched. If the import fails partway, the target Environment is in whatever state the import got to, but the source is still unchanged, so retrying is safe. The dialog distinguishes the two failure modes inline so you know which one happened.

Apply via API

If you manage configuration through Terraform, your own CI/CD, or another infrastructure-as-code tool, you can skip the Console entirely. Each Environment has its own API key; calling POST /api/v1/permissions, POST /api/v1/roles, etc. against each Environment using its API key gives you the same end state as a clone or import, with whatever orchestration your tooling prefers.

The Default Environment

Every Application has one default Environment: the env an admin lands on when they open the Application without picking a specific Environment. New Applications start with Development as the default, and the default env shows a Default badge on its card on the Tenant → Applications page.

To change it, open the Environment card's kebab menu and choose Set as Default. A confirmation dialog notes that new sessions will land on the chosen Environment; confirm and the Default badge moves. The option is disabled on the Environment that's already the default.

Changing the default only affects where a session lands by default during admin log in.

Deleting an Environment

Deleting an Environment permanently removes everything scoped to it (roles, permissions, assignments, OAuth clients, webhooks, and identity invites) for that Environment only. Its sibling Environments and the Application are untouched. Two rules guard against leaving an Application in a broken state; the Console mutes the Delete Environment action whenever a rule would block it, so you'll see it greyed out rather than hit an error:

An Application must keep at least one Environment. You can't delete the last Environment in an Application.

You can't delete the default Environment. Repoint the default to a sibling first (Set as Default on another Environment), and the old default becomes deletable.

Because deletion is irreversible, the confirmation dialog asks you to type the Environment's name before the Delete button enables, and warns that any API keys, OAuth clients, or webhooks in the Environment will stop working the instant it's deleted.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.