Create your first flag and read it from code
Go from a new organization to a flag that your app reads, and check the result with one request.
- Time
- About 10 min
- Who can do it
- Admin for every step. A Developer can do everything except create the API key.
- Where
- Projects, Feature Flags and API Keys in the console
- You finish with
- A flag you can switch on and off, read with one request
What and why#
FlagSwift lets you ship code that is switched off, then turn the feature on for the people you choose without a new deploy. This guide takes the shortest path through that idea: a project, one flag, an API key, and a request that proves your app can read the flag.
The four pieces#
| Piece | Description |
|---|---|
| Project | A group of flags for one product or service. Its key is fixed once created. |
| Flag | A named switch with a key your code reads. It has a separate on or off state in every environment. |
| Environment | A stage such as Development or Production. Your organization already has three. |
| API key | What your app sends to prove who it is. It is limited to one project and, optionally, one environment. |
When to use it#
Start here when you are new to FlagSwift, or whenever you add a flag for a feature that is not ready for everyone. The same five steps apply to every later flag, so the rest of the guides build on them.
Before you start#
- A running FlagSwift server and its address. If you host it yourself, see Self-hosting.
- An account. Signing up creates your organization and makes you its Admin, so you can do everything below. After you sign up, open the verification link emailed to you (it expires in 24 hours); that confirms your address and signs you in.
- Permissions, if you were invited instead:
projects.createto make a project,flags.createandflags.toggleto make and switch the flag, andapi_keys.createfor the key. Only Admins can create keys, so ask one to do step 4 if you are a Developer. - A way to run
curl, or an app where you can add an SDK. The SDK guide helps you choose one.
Walk through it#
Create a project
Open Projects and choose New Project. The Create Project form asks for a Name (up to 100 characters), a Key and an optional Description (up to 500). The key takes letters, numbers and single hyphens, and cannot change later because API keys and SDKs use it. A project groups the flags of one product or service.
The Create Project dialog. Create Project stays disabled until Name and Key are valid. You should see. The new project appears as a card on the Projects page. Open the card to see its flags.Create the flag
Open the project's flags (or Feature Flags from Overview) and choose New Flag. In the Create Flag form fill in Name, for example
New dashboard, and Key, for examplenew-dashboard. The key is what your code uses: lower case letters, numbers, hyphens and underscores. Leave Type on Boolean for now, then choose Create Flag.A new flag starts off
The form says so before you save: the flag is created disabled in all your environments (Development, Staging and Production on a new organization). Nothing changes for anyone until you turn it on.The Create Flag dialog with a Boolean flag. The note above the buttons lists your environments. If the dialog was opened from the all-flags page rather than from a project, it also asks for a required Project first. The Key is suggested from the Name as you type, until you edit the key yourself. A Name is required, the Description holds up to 500 characters, and the dialog is locked while the request runs.
You should see. The flag opens in the flag list with a switch for each environment, all off.Turn it on in Development
Choose Manage on the flag's row. On the Overview tab, the Environments list has one switch per environment. Turn on Development only. The Configure button beside each switch opens that environment's targeting and rollout, which you can leave alone for now.
The Environments list on the Overview tab. Each row has Configure and its own switch. A row reads
Kill switch activein red, and its switch is locked, while the kill switch is on in that environment. Rows readNN% rolloutbelow 100 and add· N targetedwhen individual users are targeted.You should see. Development shows the flag on at a full rollout. Staging and Production stay off.Create an API key
Open API Keys and choose New API Key. In Create API Key, set Name (for example “Web app (dev)”), Type, Project and Environment, and pick Expires (Never, 30 days, 90 days or 1 year). Choose Create Key.
Which key type to pick Type Description Client For browsers and mobile apps. Returns only the on or off result for one person, so it is safe to ship in an app. Server For your backend. Reads full flag configuration and can use the kill switch. The form defaults to this type. Keep it secret. Admin For automation that manages flags. Never put it in an app or a browser. Set Environment to Development so the key can only read that environment. Left on All environments, the key is project-wide and every request must say which environment it wants. Copy the key from the dialog right away. The full key is shown when you create it, and an Admin can copy it again from the key list only when key storage is enabled on your server.
The Create API Key dialog filled in for a development client key. You should see. The key is listed on API Keys with its type, project, environment and a masked value ending in its last four characters.Read the flag
Check it with one request first. Use your own server address and the key from step 4.
bash curl -s "https://flags.example.com/api/v1/evaluation/client?user_identifier=user-123" \ -H "Authorization: Bearer $KEY"The response is keyed by flag key. Each flag has
enabledand itsversion:json { "environment": "development", "hashVersion": 1, "version": "f1c2", "flags": { "new-dashboard": { "enabled": true, "version": 2 } } }Because the key is limited to one environment, you do not need to send
env. A project-wide key must add?env=development. Then add an SDK to your app. The Quickstart shows React, Node.js, Python and Go, and SDKs lists the rest.
Keep server keys out of apps
What to check#
new-dashboardshowsenabled: truewith the Development key.- Turn the Development switch off and repeat the request. It now shows
enabled: false. - The same flag is still off in Staging and Production.
- The change you made shows in the flag's History & rollback tab as a Toggled entry with your email.
Do it with the API#
Everything in the console is also a Dashboard API call. These calls use your signed-in session cookie, as described under Calling the Dashboard API, and act with your role. Every response is wrapped as { status, message, data }. Create the project, then the flag, then switch it on.
Do it with the API
The project id in the response is the projectId for the next call.
# 1. Create a project (permission projects.create)
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"}'{
"status": "success",
"message": "Project created successfully",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"name": "Web app",
"key": "web-app",
"description": "The customer site",
"color": null,
"archivedAt": null,
"createdAt": "2026-10-03T09:12:00.000Z",
"pinned": false
}
}Create the flag
In the API, name is the key your code uses and displayName is the readable name shown in the console. The response is trimmed here: each environment also carries its targeting and who last changed it.
# 2. Create a flag in it (permission flags.create)
curl -X POST "https://flags.example.com/api/flags" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"name":"new-dashboard","displayName":"New dashboard","projectId":"3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1"}'{
"status": "success",
"message": "Flag created successfully",
"data": {
"id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05",
"name": "new-dashboard",
"displayName": "New dashboard",
"description": "",
"type": "boolean",
"variants": [],
"projectId": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"environments": {
"development": { "enabled": false, "rolloutPercentage": 100, "killSwitchActive": false, "version": 1 },
"staging": { "enabled": false, "rolloutPercentage": 100, "killSwitchActive": false, "version": 1 },
"production": { "enabled": false, "rolloutPercentage": 100, "killSwitchActive": false, "version": 1 }
},
"archivedAt": null,
"owner": "you@example.com",
"permanent": false,
"pinned": false
}
}Switch it on in development
Toggle flips the current state, so send it again to switch the flag back off. It is refused with APPROVAL_REQUIRED in an environment that requires approval and for a Developer in production. API keys cannot be used on these routes; you read results with the key as in step 5. See the Projects API and Flags API for every field.
# 3. Toggle it in development (permission flags.toggle)
curl -X POST "https://flags.example.com/api/flags/b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05/toggle" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"environment":"development"}'{
"status": "success",
"message": "Flag toggled successfully",
"data": {
"id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05",
"name": "new-dashboard",
"environments": {
"development": { "enabled": true, "rolloutPercentage": 100, "version": 2 },
"staging": { "enabled": false, "version": 1 },
"production": { "enabled": false, "version": 1 }
}
}
}If something goes wrong#
A project with this key already exists
Why: Project keys are unique across your organization, archived projects included.
Fix: Choose another key, or restore the archived project that has it from Manage projects.
A flag with this key already exists in this project
Why: Flag keys are unique per project. If the message says an archived flag has the key, that flag still holds it.
Fix: Choose another key, or restore the archived flag from its Advanced tab.
Create Flag stays disabled
Why: The button waits for a Name and a valid Key. A key may contain only lower case letters, numbers, hyphens and underscores, and a type other than Boolean needs at least two valid variants.
Fix: Fix the field marked in red, then try again.
401 with AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY
Why: The request had no bearer key, or the key is unknown, revoked or expired.
Fix: Send Authorization: Bearer KEY. Create a new key if you lost the original or it expired.
403 with AUTH_ENVIRONMENT_MISMATCH, or 400 with ENV_REQUIRED
Why: A key limited to one environment was asked for another with env, or a project-wide key sent no env at all.
Fix: Drop env for a one-environment key, or add ?env=development for a project-wide key.
The flag shows enabled: false
Why: It is off in the environment your key reads, or the kill switch is active there.
Fix: Check the switch on the flag's Overview tab for that environment.
Good habits#
- Give every key its own name, such as the service and stage, so the audit log and the key list tell you whose it is.
- Use one key per environment and per service, and set an expiry for anything that is not long lived.
- Pick the flag key as you would a variable name. It cannot change, and it appears in your code for as long as the flag lives.
- Try every new flag in Development before you touch Staging or Production.
Questions#
Why is my new flag off everywhere?
Can I change the flag key later?
Which environment should my first key use?
env with it.