Flag Management

Projects and Environments

Organize feature flags by project and isolate configuration across deployment environments

Projects and Environments

Projects and environments provide the structure for managing FlagForge configuration.

A project is the top-level container for a product or application. It owns the project's environments, flags, segments, API keys, webhooks, and audit logs.
An environment is a named deployment target within a project, such as development, staging, or production. Flag configuration, including enabled state, defaults, and targeting rules, is stored separately for each environment.

This lets you use the same flag definition across stages while changing its behavior safely. For example, a flag can be enabled for internal testing in development and remain disabled in production.

Before you begin

Management endpoints require a server API key in a Bearer header:

http

Authorization: Bearer <server-key>

Server keys can create and list projects and environments. Client keys are intended for flag evaluation and cannot manage these resources. See Authentication for the complete credential model.

Set variables for the API address and your server key before running the examples:

bash

FLAGFORGE_URL=http://localhost:4000
SERVER_KEY="srv_your-server-key"

The API exposes interactive request documentation at http://localhost:4000/docs and the OpenAPI document at http://localhost:4000/openapi.json.

Create the project structure

Use this sequence when setting up a new application:

Send a project key, display name, and optional description to POST /v1/projects:

bash

curl -sS -X POST "$FLAGFORGE_URL/v1/projects" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "checkout",
    "name": "Checkout",
    "description": "Flags and remote configuration for the checkout application"
  }'

The response contains the project id. Save that identifier for the environment requests.

json

{
  "id": "clx_example_project",
  "key": "checkout",
  "name": "Checkout",
  "description": "Flags and remote configuration for the checkout application",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

Project keys are unique and URL-safe. Creating another project with the same key returns a conflict.

Create one or more environments under the project with POST /v1/projects/{projectId}/environments:

bash

PROJECT_ID="clx_example_project"

curl -sS -X POST "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "development",
    "name": "Development"
  }'

Expected response:

json

{
  "id": "clx_example_environment",
  "projectId": "clx_example_project",
  "key": "development",
  "name": "Development",
  "createdAt": "2025-01-15T10:02:00.000Z"
}

Repeat the request with staging or production as needed. An environment key must be unique within its project, so the same key can be used in different projects.

Confirm the project and its environments with the management API:

bash

curl -sS "$FLAGFORGE_URL/v1/projects" \
  -H "Authorization: Bearer $SERVER_KEY"

curl -sS "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $SERVER_KEY"

Project and environment list responses use a data array:

json

{
  "data": [
    {
      "id": "clx_example_environment",
      "projectId": "clx_example_project",
      "key": "development",
      "name": "Development",
      "createdAt": "2025-01-15T10:02:00.000Z"
    }
  ]
}

After you have the project ID and environment keys, create typed flags in the project. Then configure each flag's per-environment targeting and default variations. Continue with Flags and Variations.

How isolation works

FlagForge separates a flag's definition from its environment-specific behavior.

Configuration	Scope	Examples
Flag definition	Project	Flag key, name, type, and named variations
Flag behavior	Project and environment	Enabled state, default variation, off variation, and targeting rules
Evaluation request	Client key and environment	The environment selected for bootstrap or evaluation

A flag belongs to a project and is identified by its key within that project. Its possible values, or variations, are defined once. Each environment then determines which variation is returned when the flag is disabled, when no targeting rule matches, or when a targeting rule matches a context.

When a new environment is created, FlagForge creates a disabled configuration for each flag that already exists in the project. The first variation is selected as the default variation and the last variation as the off variation; targeting rules start empty. Review and update these settings before using the environment for application traffic.

Note:

Use the environment key consistently in application configuration. Bootstrapping or evaluating against the wrong environment can produce valid results from a different set of defaults and targeting rules.

Choosing a project and environment layout

Use a separate project when flags, ownership, or API-key scope should be independent. Use environments within one project when the stages share the same flag definitions but need different rollout behavior.

A common layout is:

Project	Environments
`checkout`	`development`, `staging`, `production`
`mobile-api`	`development`, `production`

The SDK selects an environment during initialization, while management requests use the project ID in their URL. This keeps administrative configuration and application evaluation aligned:

typescript

const client = new FlagForgeClient({
  baseUrl: "http://localhost:4000",
  clientKey: "cli_your-client-key",
  environment: "production",
});

The client key must belong to the project being evaluated. For local evaluation, the SDK bootstraps the definitions for the selected environment from GET /v1/config; see the SDK Client Guide.

PreviousConfiguration NextFlags and Variations