Core concepts

Hierarchy

Environments

Each project has up to three fixed roles:

• development is permanent. You cannot rename or delete it.
• staging and production are optional add-ons (at most one each); require a paid plan to add.
• Both staging and production are production-tier from an API perspective; the names are organizational.

Test keys return 403 from origins that are not loopback:

• .local hostnames (e.g. myapp.local)
• Private LAN IPs (RFC1918): 10.x.x.x, 172.16.x.x-172.31.x.x, 192.168.x.x

On the free plan, RFC1918 origins are always blocked. Phone-on-WiFi or homelab testing needs a paid plan plus an ft_live_ key in staging or production.

Features

Types

Key rules

• Unique per project (case-sensitive).
• Immutable after create. Choose a stable name client code will use forever.
• Format: starts with a letter; then letters, digits, _, or -; 1-64 characters.

Project default vs environment activation

Features are defined at project level with a defaultValue. Activation (whether the feature is on) is set per environment. Per-environment value overrides are optional (usesDefault: false).

Two levels in the dashboard:

1. Feature definitions: define keys, types, and default values, and deprecate features you are retiring.
2. Environment → Features: use the switch to activate, the edit icon to change the value, and the … menu for Turn off, Use default, or Clear.

Resolution

For each environment, FeatureToggle computes an effective value and effective enabled state:

• Off when there is no FeatureValue row or enabled: false.
• On when FeatureValue.enabled === true.
• When on and usesDefault: true, value is the live project defaultValue.
• When on and usesDefault: false, value is the stored override.

value and enabled are independent for all types (including boolean).

Public API behavior:

• Only enabled features are returned.
• Disabled features are omitted from bulk reads and return 404 on single-feature lookup.
• The SDK caches only enabled features. isEnabled('missing') returns false; getValue('missing') returns undefined.

Feature lifecycle

Features are never individually deleted. Remove features by deleting the parent project (cascades everything).

Disable and deprecate are independent controls. A feature can be disabled, deprecated, or both.

Deprecation

Mark a feature deprecated (Deprecate on Feature definitions) when you are migrating away but still need it to resolve during rollout.

• Optional Replacement feature (inFavorOf) points to another feature in the same project.
• Enabled deprecated features are included in default API responses.
• Pass deprecated=false on GET /v1/features to exclude them.
• The SDK logs a one-time warning per deprecated key when accessed; includes the replacement when set.

Example API payload:

{
  "key": "old-checkout",
  "type": "boolean",
  "value": true,
  "enabled": true,
  "deprecated": true,
  "inFavorOf": "new-checkout"
}

API keys

Create keys in Environment → API keys (Create key). Multiple Active keys per environment are allowed.

Version and freshness

Each environment has a monotonic version number that increments when feature data affecting that environment changes. The public API exposes this as an ETag on bulk reads.

When you toggle a feature:

1. The environment version bumps.
2. Connected SDKs receive an SSE features-changed event.
3. The SDK refreshes and picks up new values.

Details: Caching and syncs

What the client app cannot do via API

The public feature API is read-only. There is no HTTP API to:

• Create, update, or delete features
• Manage projects, environments, or keys
• Access Billing or organization profile

All management happens in the dashboard.