Feature flags

Feature flags let you turn features on and off without a deploy. A flag is a boolean, scoped per environment, and its result for the signed-in user is delivered in the session token — so your app reads it with no extra network request.

Flags are managed in the Torii dashboard (Project → Feature flags) and read in your app through the useFeatureFlags hook (or straight from the token for non-React stacks).

Concepts

• A flag is identified by a key (e.g. new-checkout) — a lowercase, hyphenated slug you reference in code. The key is stable across environments, so the same useFeatureFlag('new-checkout') works in sandbox and production.
• State is per environment. A flag is created across all of a project’s environments at once, but whether it’s on, who it targets, and its default value are set independently per environment — so you can switch it on in sandbox and leave it off in production until you’re ready.
• The enabled set rides the session token. At sign-in (and on every session refresh) Torii evaluates the flags for the user and writes the enabled keys into the token’s feature_flags claim. Your app reads that claim — no per-check API call.

Managing flags in the dashboard

Under Project → Feature flags, pick an environment (Sandbox / Production) with the environment switcher, then:

1. Create a flag — give it a name and a key. It’s created across every environment, starting off.
2. Open the flag — the list shows each flag and its status; click a row to open its detail page (owner, created date, rules, and delete).
3. Flip it on (under Rules) — the on/off switch is the per-environment master kill switch. When off, the flag is off for everyone regardless of targeting; when on, the targeting below decides who.
4. Choose who sees it (targeting) — independent of the switch, so you can leave a rollout configured and just toggle the flag off:
   • None — no one (even while the switch is on).
   • All — everyone in the environment.
   • Some — the users you target, and/or a percentage rollout; everyone else is off.
5. Roll out gradually (in Some mode) — set a rollout percentage to reach that fraction of users on top of any explicit targets. Rollout is deterministic and sticky per user: raising the percentage only ever adds users, so someone who’s in at 20% stays in at 50%.

Reading flags in your app

React

Use useFeatureFlags (or the single-flag useFeatureFlag). It reads the feature_flags claim from the session — no network request:

import { useFeatureFlag } from '@torii-js/torii-react';

function Checkout() {
  const newCheckout = useFeatureFlag('new-checkout');
  return newCheckout ? <NewCheckout /> : <LegacyCheckout />;
}

import { useFeatureFlags } from '@torii-js/torii-react';

function Nav() {
  const { flags, isEnabled } = useFeatureFlags();
  // `flags` is the full list of enabled keys for the current user.
  return isEnabled('beta-banner') ? <BetaBanner /> : null;
}

Other stacks (read the claim)

The enabled keys live in the feature_flags claim of the access token (a JSON array of strings), so any language can read them after verifying the token:

// After you've decoded/verified the Torii access token:
const flags: string[] = claims.feature_flags ?? [];
if (flags.includes('new-checkout')) {
  // ...
}

Propagation

Because flags ride the session token, a change takes effect on the user’s next token refresh — up to the access-token lifetime, not instantly. Flipping the flag’s off switch is the fastest lever; it stops the flag being emitted for new tokens regardless of targeting.

Not in this version

Feature flags are intentionally minimal today: flags are boolean (no string/number/JSON variants), and there’s no built-in A/B analytics or scheduled rollout. Percentage rollout and org/user targeting cover the common release-management cases.