Flags & flag types

A flag is a named switch your code reads at runtime. Each flag has a key, a type, and one or more values, and exists once per project (with separate targeting per environment).

Flag keys

A key is the string you reference in code. Keys must be lowercase_snake_case — they match the pattern ^[a-z][a-z0-9_]*$:

• Good: new_checkout, search_v2, dark_mode, max_results
• Rejected: NewCheckout, new-checkout, 1_flag

A key is unique within a project. Pick descriptive names — you'll accumulate dozens of flags, and clear names prevent confusion.

Flag types

Switchbox supports four value types:

Boolean flags are the classic on/off switch — use enabled(). String, number, and json flags carry a value (a config knob, an A/B variant, a limit, or a whole structured blob) — use getValue(). A json flag is handy when you want to ship a small piece of configuration — a feature's settings, a list of allowed values — as one flag.

# boolean
if client.enabled("dark_mode", user={"user_id": "42"}):
    ...

# string / number
algo = client.get_value("search_algorithm", user={"user_id": "42"}, default="v1")
limit = client.get_value("max_results", user={"user_id": "42"}, default=10)

# json — returns a parsed object/array
cfg = client.get_value("checkout_config", user={"user_id": "42"}, default={})

Default value vs enabled value

Non-boolean flags have two values, and which one a user gets is exactly the question targeting answers:

• default_value — what a user gets when the flag is off, or when no rule and no rollout matches them. This is the safe fallback.
• enabled_value — what a matched user gets (a targeting rule hit, or they fell inside the rollout percentage).

So a string flag can serve "v2" to enterprise customers (enabled_value) and "v1" to everyone else (default_value). For a boolean flag the on-value is implicitly true, so there's only the one value to set.

Always pass a sensible default to get_value() in code too. It's the value the SDK returns if the flag doesn't exist or no config has loaded yet — your last line of defence.

Scope: one flag, many environments

A flag is defined once per project, but its targeting (on/off, rules, rollout %) is set per environment. The same new_checkout flag can be on in development and off in production. Non-boolean values are authored at the flag level and can optionally be overridden per environment. See Environments & SDK keys.

Next

• Targeting rules — serve the enabled value to specific users.
• Percentage rollouts — serve it to a fraction of users.