Core Concepts

This page explains the key concepts in Flipswitch that you'll use to manage feature flags.

Organizations

An organization is the top-level container for all your projects. Organizations have:

• Members - Users who can access projects
• Groups - Collections of users with shared permissions
• Projects - Containers for flags and environments

Projects

A project typically represents an application or service. Each project contains:

• Flags - Feature flags with variants and rules
• Environments - Isolated configurations (dev, staging, prod)
• Segments - Reusable user groups for targeting

Environments

Environments allow you to configure flags differently for each stage of your deployment pipeline.

Each environment has its own:

• Flag states (enabled/disabled)
• Targeting rules
• API keys

Feature Flags

A feature flag controls the behavior of your application. Flags have:

Key

A unique identifier using kebab-case (e.g., dark-mode, new-checkout-flow).

Type

The data type of the flag value:

Variants

Named values the flag can return. Every flag has at least two variants:

• Default variant - Returned when the flag is disabled or no rules match
• Additional variants - Used for A/B testing or feature variations

Default Value

The value returned when:

• The flag is disabled
• No targeting rules match
• An error occurs during evaluation

Targeting

Targeting determines which users see which variant of a flag.

Evaluation Context

Context is user/request data passed during flag evaluation:

const context = {
  targetingKey: 'user-123',      // Required: unique user identifier
  email: 'user@example.com',     // Custom attributes
  plan: 'premium',
  country: 'SE'
};
 
const value = await client.getBooleanValue('feature', false, context);

Targeting Rules

Rules evaluate context attributes to determine the flag value:

IF email ENDS_WITH "@beta.com"
  THEN return true
ELSE IF plan EQUALS "enterprise"
  THEN return true
ELSE
  THEN return false

Operators

Available comparison operators:

Segments

Segments are reusable groups of users defined by targeting rules.

Instead of repeating rules across flags:

IF email ENDS_WITH "@company.com" OR plan EQUALS "enterprise"

Create a segment called beta-users and reference it:

IF user IN SEGMENT "beta-users"

Segments make it easy to:

• Maintain consistent targeting across flags
• Update targeting in one place
• Create meaningful user groups (beta testers, enterprise customers, internal users)

Percentage Rollouts

Percentage rollouts gradually release a feature to a portion of users:

10% of users -> variant-a
20% of users -> variant-b
70% of users -> control

Rollouts are deterministic - the same user always gets the same variant based on their targetingKey hash. This ensures:

• Consistent experience for each user
• Reproducible results for debugging
• Statistically valid A/B tests

API Keys

API keys authenticate SDK requests to the Flag API. Each environment has its own keys.

Real-Time Updates (SSE)

Flipswitch uses Server-Sent Events (SSE) to push flag changes to connected clients instantly.

When you toggle a flag in the dashboard:

1. The server broadcasts a flag-change event
2. Connected SDKs receive the event
3. SDKs invalidate their cache
4. Next evaluation fetches the fresh value

This enables:

• Instant kill switches for broken features
• Real-time A/B test adjustments
• Dynamic configuration without redeployment