Skip to content
FlagSwiftDocs

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.archive and projects.delete and every environments.* 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.

Projects and environments compared
ThingBelongs toDescription
ProjectOrganizationGroups flags. API keys are created for one project. Its key cannot change after creation.
EnvironmentOrganizationA stage such as Development. Its key is what SDKs use to select it, and it cannot change.
What each field allows
FieldTypeDescription
Project namestringRequired, up to 100 characters. You can change it.
Project keystringLetters, numbers and single hyphens, such as web-app. Stored in lower case, unique in the organization, fixed after creation.
Project descriptionstringUp to 500 characters.
Environment namestringThe label people see, up to 50 characters. You can change it.
Environment keystringLower 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#

  1. 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.
  2. 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.
  3. Add an environment if you need one

    Choose New Environment. In Create Environment, set a Name such as QA and a Key such as qa (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.
  4. 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 production environment is always a production environment, and its switch is locked on.

  5. 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.
The Archive project dialog, and the same dialog while the request runs. It states how many flags and keys are affected, then waits for you.
Restoring is not destructive, so the confirm button is the brand colour rather than red.
Delete project. The button stays disabled until the project key is typed. If the project still has active flags, a red notice asks you to archive them first.

Archiving takes SDKs offline

Archiving a project makes every API key for it fail immediately, so apps that use them stop receiving flags and fall back to their defaults. Check the key list first, and make sure your SDKs have sensible fallbacks.

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.

Request
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"}'
Response
{
  "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.

Request
# 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}'
Response to the first call
{
  "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?
So that Production means the same thing everywhere. Approval rules and role restrictions are set once on the environment, and every project follows them.
Can I rename an environment key?
No. You can change its name (the label), but its key is what SDKs, API keys, saved versions and flag history refer to, so it is fixed. Choose it as you would a database name.
What does an environment key limit on an API key do?
A key limited to one environment can only read that environment, and requests need no env parameter. A project-wide key must say which environment it wants.
Does archiving a project delete anything?
No. Flags become read-only and keys stop working until you restore the project. Delete is a separate, permanent step for archived projects with no active flags.

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.