Skip to content
FlagSwiftDocs

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#

What you create and what it is for
PieceDescription
ProjectA group of flags for one product or service. Its key is fixed once created.
FlagA named switch with a key your code reads. It has a separate on or off state in every environment.
EnvironmentA stage such as Development or Production. Your organization already has three.
API keyWhat 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.create to make a project, flags.create and flags.toggle to make and switch the flag, and api_keys.create for 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#

  1. 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.
  2. 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 example new-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.
  3. 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 active in red, and its switch is locked, while the kill switch is on in that environment. Rows read NN% rollout below 100 and add · N targeted when individual users are targeted.

    You should see. Development shows the flag on at a full rollout. Staging and Production stay off.
  4. 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
    TypeDescription
    ClientFor browsers and mobile apps. Returns only the on or off result for one person, so it is safe to ship in an app.
    ServerFor your backend. Reads full flag configuration and can use the kill switch. The form defaults to this type. Keep it secret.
    AdminFor 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.
  5. 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 enabled and its version:

    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

Only Client keys are safe in a browser or mobile app. Server and admin keys stay in your backend or your secrets manager. If one leaks, rotate it from the API Keys page.

What to check#

  • new-dashboard shows enabled: true with 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.

Request
# 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"}'
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": 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.

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

Request
# 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"}'
Response
{
  "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?
A new flag is always created disabled in every environment, with a 100% rollout ready for when you turn it on. This means creating a flag never changes what anyone sees.
Can I change the flag key later?
No. The key is what your code and every SDK use, so it is fixed once created. You can change the display name and description at any time.
Which environment should my first key use?
Development. A key limited to one environment cannot read the others, and you do not need to send env with it.
Do I need to deploy again to turn the flag on?
No. Your app reads the current state from FlagSwift, and SDKs pick up a change within their refresh interval (30 seconds by default) or at once with streaming turned on.