Environments
How Environments isolate access-control configuration inside an Application.
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. An Environment can also be marked as production, which records that it holds real end users. Marking is one-way, and the seeded Production Environment starts marked; see Manage Applications and Environments.
Access Control Context
Environment is the context for Access Control
When you select an Environment, in the Console's Application and Environment switcher or by selecting its card on Tenant → Applications, every page under Access Control (Overview, Permissions, Roles, Identities, Integrations, Hierarchy, Organizations) re-scopes to that Environment's 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 Configuration to… 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
The Console has four mechanisms for moving configuration from one Environment to another: three primitives plus one guided flow built on top, and the rules below are the same across all four. The API is a fifth route, covered last.
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
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, their Environment memberships, API keys and secrets are left alone. Role assignments are not: replacing the Environment's roles and the hierarchy removes every assignment of those roles in the target (an organization's own roles stay, with their assignments), and pending invitations to it are deleted. Everything in the configuration scope (permissions, the Environment's 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. The import itself runs in one transaction, so a failed import leaves the target as it was, and the source is unchanged either way, 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 for most of it. Each Environment has its own API keys; calling POST /api/v1/permissions, POST /api/v1/roles, the hierarchy endpoints, POST /api/v1/webhooks, and POST /api/v1/oauth-clients against each Environment with one of its keys builds the same permissions, roles, hierarchy, webhooks, and OAuth clients 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 affects two things: where an administrator lands when they open the Application without picking an Environment, and which Environment the public API (/api/v1/*) acts on when it is called with an administrator's bearer token instead of an API key. An API key always acts on the Environment it was created 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:
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.
Tell us how we can improve this guide.