Set up projects and environments
Use projects to group flags by product, and environments to give each stage of delivery its own state for every flag.
- Time
- About 8 min
- Who can do it
- Admin for environments, archiving and deleting. Admins and Developers can create projects.
- Where
- Projects, Projects > Manage projects and Environments in the console
- You finish with
- A project per product and the environments you ship through
What and why#
What they are#
A project is a folder of flags for one product or service. An environment is a stage of delivery, such as Development or Production. Every flag has its own on or off state, rollout and targeting in each environment, so you can finish a feature in Development while Production stays untouched.
When to use each#
- Make a project for each product or service that ships on its own, so its API keys and cleanup stay separate. Segments are organization-wide unless you scope one to a project when you create it.
- Add an environment for each place your code runs that needs its own flag state, for example QA or a demo site. Keep the list short, because every environment adds a switch to every flag.
- Mark an environment as production when real users touch it, and require approval when a second person should review changes there.
Before you start#
- Permissions:
projects.create(Admin, Developer) to create a project;projects.update,projects.archiveandprojects.deleteand everyenvironments.*change (Admin only). - An idea of how you ship: for example Development, Staging and Production. You already have those three if you followed Create your first flag.
- If production changes should be reviewed, read Put production behind review before you switch on approval.
How they fit together#
A project holds flags. An environment holds the on or off state, rollout and targeting of every flag. Environments belong to the organization, not to a project, so Production means the same thing everywhere. A flag has the same key in all environments and its own state in each.
| Thing | Belongs to | Description |
|---|---|---|
| Project | Organization | Groups flags. API keys are created for one project. Its key cannot change after creation. |
| Environment | Organization | A stage such as Development. Its key is what SDKs use to select it, and it cannot change. |
| Field | Type | Description |
|---|---|---|
| Project name | string | Required, up to 100 characters. You can change it. |
| Project key | string | Letters, numbers and single hyphens, such as web-app. Stored in lower case, unique in the organization, fixed after creation. |
| Project description | string | Up to 500 characters. |
| Environment name | string | The label people see, up to 50 characters. You can change it. |
| Environment key | string | Lower case letters, numbers, hyphens and underscores, up to 50, with no leading, trailing or doubled separators. Unique in the organization and fixed after creation. |
Walk through it#
Create a project for each product
In Projects, choose New Project. The Create Project form asks for Name, Key (hint: letters, numbers and hyphens) and an optional Description. Pick a color if you want to tell projects apart at a glance (red, orange, amber, green, teal, blue, indigo, purple, pink or gray; it is optional and only a label). Edit, archive and delete live in Manage projects, which has Active, Archived and All tabs and a search over name, key and description.
You should see. The project appears on Projects. Pin the ones you open often. You can pin up to 3 projects, and pins are yours alone.Review the environments
Open Environments. A new organization has Development, Staging and Production. Each row shows how many flags are on in it. The default environments can be renamed but not removed, and Production cannot be downgraded.
The environment list. Badges show Default, Production and Approval required; the count is flags on out of all flags. Add an environment if you need one
Choose New Environment. In Create Environment, set a Name such as
QAand a Key such asqa(hint: used by SDKs to select this environment). Choose the key as you would a database name, because it cannot change later. Choose Create Environment.The Create Environment dialog. The Production switch starts off. As with flags, the Key is suggested from the Name while you type. The Key becomes lower case, and a duplicate shows the error under Troubleshooting.
It reaches every flag
The form says the environment is added, disabled, to every existing flag. Flags you create later include it automatically.You should see. The environment is listed last. Open any flag and it appears in the Overview tab's Environments list with its switch off.Mark production and require approval
Edit the environment (the dialog is titled with its name) and switch on Production environment: Developers and Product managers can then view flags there but not toggle, change rollouts or targeting, or use the kill switch. Release managers and Admins keep full access. Switch on Require approval to stop direct changes: someone proposes a release, a reviewer approves it, and the kill switch still works at once. Choose Save Changes.
The edit dialog. Key is read only, and Production is locked on for the default production environment. The default
productionenvironment is always a production environment, and its switch is locked on.Order and remove
Drag environments to set the order they appear in on flag lists. To remove a custom environment, use its remove action and type its key to confirm. The dialog first tells you how many flags it will be stripped from and how many of them are currently on. Removal deletes its configuration from every flag and its change history, and cannot be undone.
Archive, restore and delete a project#
- Archive project: its flags become read-only and leave the dashboard and stats, its API keys stop working right away, and it disappears from project pickers. Nothing is deleted.
- Restore project: you confirm first, then everything comes back as it was, and keys start working again at once.
- Delete: permanent. The project must be archived and have no active flags, so archive its flags first. Deleting removes the project, its flags with their version and change history and its API keys. Organization-wide segments are kept; segments scoped to the project are deleted with it. The audit log keeps a record. You type the project key to confirm.
Archiving takes SDKs offline
What to check#
- Each environment you expect is listed, in the order you want.
- Production shows as a production environment, and approval is on if you want review.
- Create a test flag and confirm it appears off in every environment, including
production. - Sign in as a Developer and confirm the toggle for production is unavailable there.
Do it with the API#
These Dashboard API calls use a signed-in session cookie (see Calling the Dashboard API) and act with your role. Responses are wrapped as { status, message, data }.
Create a project
Needs projects.create (Admin, Developer). In the API key is the project key and cannot be changed afterwards. color is optional.
curl -X POST "https://flags.example.com/api/projects/create" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"name":"Web app","key":"web-app","description":"The customer site","color":"blue"}'{
"status": "success",
"message": "Project created successfully",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"name": "Web app",
"key": "web-app",
"description": "The customer site",
"color": "blue",
"archivedAt": null,
"createdAt": "2026-10-03T09:12:00.000Z",
"pinned": false
}
}Add an environment and require approval
In the API, name is the environment key (lower case, up to 50 characters) and displayName the label. Editing needs displayName in the body every time. Archive and restore a project with POST /api/projects/{id}/archive and /restore, and reorder environments with PUT /api/environments/order. The Projects and environments API page lists every field.
# Add an environment (environments.create, Admin)
curl -X POST "https://flags.example.com/api/environments" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"name":"qa","displayName":"QA","isProduction":false}'
# Require approval on production (environments.update, Admin)
curl -X PATCH "https://flags.example.com/api/environments/ENVIRONMENT_ID" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"displayName":"Production","isProduction":true,"requiresApproval":true}'{
"status": "success",
"message": "Environment created successfully",
"data": {
"id": "9a41c7e2-3d58-4b0f-a6c1-7e2f5d8b1c34",
"name": "qa",
"displayName": "QA",
"order": 3,
"isDefault": false,
"isProduction": false,
"requiresApproval": false
}
}If something goes wrong#
A project with this key already exists
Why: Project keys are unique across the organization, and the key is stored in lower case.
Fix: Pick another key, or restore the archived project that has it.
An environment with this name already exists
Why: Environment keys are unique in the organization.
Fix: Look for it on the Environments page before you add it.
The production environment cannot be downgraded
Why: The default production environment always stays a production environment.
Fix: Create a custom environment if you need a non-production one.
Default environments cannot be removed
Why: Development, Staging and Production can be renamed but not deleted.
Fix: Only custom environments can be removed.
Delete is refused: the project still has active flags (PROJECT_HAS_ACTIVE_FLAGS)
Why: A project must be archived and have no active flags before it can be deleted.
Fix: Archive the project's flags first, or keep the project archived.
This project is archived (PROJECT_ARCHIVED)
Why: Flags and keys in an archived project are read-only.
Fix: Restore the project to make changes.
Environments have changed. Refresh the page and try again
Why: Someone added or removed an environment while you were reordering.
Fix: Reload and drag again.
Questions#
Why is an environment shared by every project?
Can I rename an environment key?
What does an environment key limit on an API key do?
env parameter. A project-wide key must say which environment it wants.Does archiving a project delete anything?
Good habits#
- Keep environments few and meaningful. Every new one is added to every flag, so each adds a switch to maintain.
- Mark every environment that real users touch as a production environment, not only the one called Production.
- Give each product or service its own project, so its API keys and cleanup are separate. Segments are organization-wide unless you scope one to a project when you create it.
- Prefer archiving over deleting. Archiving is reversible and keeps history.