Environments
Give each stage of your release process its own flag values, rules, and credentials.
An environment is a separate configuration space inside a workspace. A flag can be on with a 50% rollout in Development and off in Production. Changes in one environment do not affect the others.
New workspaces start with two environments, in this order:
| Position | Environment | Key | Color | Production marker |
|---|---|---|---|---|
| 1 | Development | development | Sky | No |
| 2 | Production | production | Rose | Yes |
What is shared and what is per environment
| Shared across environments | Per environment |
|---|---|
| Flag key and type | Variant values |
| Name, description, tags, metadata | Default variant and off variant |
| Segments | Enabled state |
| Targeting rules |
- When you create a flag, Toggld copies its variants, default variant, and off variant to every environment. Each environment then keeps its own copy, so later edits affect only one environment.
- When you create an environment, it goes last in the order. Toggld copies the variants, default variant, and off variant of every flag from the environment before it. Every flag starts off in the new environment, with no rules.
- Deleting a flag removes it from every environment.
Credentials select the environment
Every secret key and public token belongs to exactly one environment. Your application never sends the environment name. The credential decides it.
- A server SDK key for Production always evaluates Production values.
- A management key reads and writes the configuration of its own environment. Changes to shared fields, such as the name or tags, still apply everywhere.
- Each environment has one public token for client-side code.
To use flags in several environments, create one key per environment and configure each deployment with its own key. See API keys.
Manage environments
Open Settings → Environments. The page lists the environments in order. Owners and admins can manage environments. Members and readers see the list, but they cannot change it.
- Add environment: enter a Display name and a Key, such as
Previewandpreview. Choose a Color, and turn on Production if the environment serves live users. Then select Add environment. - Edit: change the display name, the key, the color, or the production marker, then select Save.
- Reorder: drag a row by its handle. See Environment order.
- Delete…: in the row's ⋯ menu. See Delete an environment.
Environment order
Environments have an order. The first environment is marked Opens first.
- The dashboard opens the first environment when you do not choose one. It does not remember the last environment that you used.
- The environment tabs on the flags list and on flag pages follow the order.
- Onboarding creates its first flag in the first environment. For a new workspace, this is Development.
- A new environment goes last, and it copies its flag values from the environment before it.
To change the order, drag a row by its handle. With the keyboard, focus a handle and press ↑ or ↓. Home and End move the row to the top or the bottom. The row's ⋯ menu also has Move up, Move down, and Move to top.
The order saves when you drop the row. Order saved appears with Undo. If the save fails, the list keeps your new order and shows Try again and Revert. Until you select one, Toggld still has the old order.
There is no default environment. Every API key and public token belongs to one environment, and every MCP tool that reads or changes flag values takes an environment argument. The order never decides where a change lands.
Environment colors
Each environment has a color. The dashboard shows it as a dot next to the environment name, and as the top edge of the selected environment tab. The color helps you see which environment you are working in. It does not change how evaluation works.
When you add an environment in the dashboard, it suggests a color that no other environment uses yet. The API and MCP tools use gray when you do not send a color.
The production marker
Production is a label. Several environments can carry it. It does not change how evaluation works, but the dashboard adds these protections:
- Environment tabs show a Live badge, and Settings → Environments shows a Production badge.
- On the flags list, the switch asks you to confirm before it turns a flag on or off.
- On a flag page, the save bar warns that saving changes what live users get.
- The delete dialog warns that live users get the fallback values in their code at once.
Change an environment key
The environment key identifies the environment in dashboard URLs, in MCP tools, and when you create keys through the API. To change it, select Edit, then Change key. The dialog warns that apps and scripts that select the environment by its old key stop finding it until you update them. Select Save and change key to confirm, or Keep old key to undo the change. Existing SDK keys and public tokens keep working and stay in the same environment.
Delete an environment
Open the row's ⋯ menu and select Delete…. Type the environment key to confirm, then select Delete environment. Deleting an environment does this:
- It removes the flag values and rules of that environment.
- It revokes every secret key of that environment.
- It removes the environment's public token.
You cannot undo the deletion. You cannot delete the last environment. Add another environment first.
Applications that use the environment's keys stop getting flag values when you delete it, and fall back to the values in their code. Move them to another environment first.
Copy changes between environments
Toggld has no built-in promotion between environments. To copy a configuration, apply the same change in each environment in the dashboard, or script it with one management key per environment. Each environment's flag has its own version, so send expectedVersion in each request. See Update part of a flag.
Manage environments with the API
Environment endpoints live under /api/v1/environments and require a management key. Updates and deletions take the environment ID.
List the environments. The response is in order, first environment first:
curl https://api.toggld.io/api/v1/environments \
-H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"Create an environment. It goes last in the order:
curl https://api.toggld.io/api/v1/environments \
-H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{ "key": "staging", "name": "Staging", "color": "amber", "isProduction": false }'Change the order. Send every environment ID in the workspace exactly once, in the new order:
curl -X PUT https://api.toggld.io/api/v1/environments/order \
-H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{ "environmentIds": ["ENVIRONMENT_ID_1", "ENVIRONMENT_ID_2"] }'The response lists the environments in their new order. The audit log records an environment.update event for each environment that moved.
These requests return HTTP 409 with the error EnvironmentConflict:
- A new order that leaves out an environment, names an unknown one, or names one twice.
- Deleting the last environment.
See the API reference for every field.