Custom Targets

Feature flags can target WorkOS organizations and users. Many rollouts need a boundary that WorkOS does not model, such as a workspace inside a customer’s company, a billing account, or one of your own deployment environments. Custom targets let a flag name those resources directly, without modeling them as placeholder users or organizations.

A custom target has two parts:

• A target type, a lowercase slug that names a class of resource in your application, such as workspace, account, or tenant. The dashboard calls this the rule type.
• A target ID, the identifier of one resource of that type, such as ws_123. WorkOS stores and matches the ID exactly as you enter it. It does not resolve the ID to a name or check that the resource exists.

Custom targets are exact matches only. A rule matches the workspace with ID ws_123 only when the evaluation context names exactly that type and ID. Custom targets do not add segments or percentage rollouts.

Custom targets are managed in the WorkOS Dashboard. The targeting API currently accepts organization and user targets only.

A target type should name a class of resource in your application, such as workspace, account, tenant, project, or environment.

When choosing target IDs:

• Use the identifier your system already emits. Target IDs are case-sensitive, so pass the canonical machine identifier, such as ws_01J9..., rather than a display name typed by hand.
• Keep sensitive personal data out of types and IDs. Both are visible in the dashboard, delivered to every runtime client polling the environment, and recorded in audit logs.

To follow this guide, you’ll need:

• A feature flag in your WorkOS Dashboard. The quick start walks through creating one.
• The runtime client in your application, from one of these SDKs:
  • @workos-inc/node version 10.11.0 or later. Earlier versions ignore custom targets and evaluate organization and user targeting only. Versions before 12.0.0 also ignore rules that serve false.
  • The workos Python package version 10.8.0 or later.

Like organization and user targets, custom targets are configured per environment. Open the flag in your WorkOS Dashboard and find the card for the environment you want to configure. To configure a different environment, click Edit in X to switch your active environment.

1. Set the environment’s rule to Some. The Organizations and Users targeting rows appear.
2. Click Add custom targeting rule.
3. Choose a rule type. The list shows every type already saved in the project. To add a new type, enter its slug and choose Create new rule type. The built-in organization and user types cannot be created as custom types.
   
4. Enter one or more rule IDs, separated by commas, then press Enter or click Add. Each ID is added to the rule, where it can be removed before saving.
   
5. Click Add custom rule.

The rule appears as a new row labeled with its type, listing each ID.

A rule type is saved once for the whole project, so a type created while configuring your staging environment is already available when you configure production. Rule IDs are scoped to a single environment. Add them separately in each environment where the flag should target those resources. The type stays available after its last target is removed, and its slug cannot be changed.

Toggle the flag on for the environment, as you would for a flag targeted at organizations or users. Once the flag is on, the environment’s status line shows the value being served and counts the custom targets alongside its organizations and users.

A flag that is off evaluates to false for every context, no matter which targets are configured, so turning the flag off works as a kill switch without changing the targeting you have set up.

Pass the resource being evaluated to the runtime client, keyed by its target type. In Node, each value is an object with the resource’s id. In Python, each value is the ID itself.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const client = workos.featureFlags.createRuntimeClient();

client.on('error', (error) => {
  console.error('Feature flag poll failed:', error.message);
});

await client.waitUntilReady({ timeoutMs: 5000 });

// Evaluate for a single workspace
const isEnabled = client.isEnabled('collaborative-editing', {
  workspace: { id: 'ws_01J9ZK3P6Q5T8N4M2R7X1V0B9C' },
});

// Combine built-in and custom targets in one context
const isEnabledForRequest = client.isEnabled('collaborative-editing', {
  user: { id: 'user_01E4ZCR3C56J083X43JQXF3JK5' },
  organization: { id: 'org_01EHQMYV6MBK39QC5PZXHY59C3' },
  workspace: { id: 'ws_01J9ZK3P6Q5T8N4M2R7X1V0B9C' },
});

from workos import WorkOSClient

workos = WorkOSClient()

flags = workos.create_feature_flags_runtime_client()
flags.start()
flags.wait_until_ready(timeout=5)

# Evaluate for a single workspace
is_enabled = flags.is_enabled(
    "collaborative-editing", {"workspace": "ws_01J9ZK3P6Q5T8N4M2R7X1V0B9C"}
)

# Combine built-in and custom targets in one context
is_enabled_for_request = flags.is_enabled(
    "collaborative-editing",
    {
        "user": "user_01E4ZCR3C56J083X43JQXF3JK5",
        "organization": "org_01EHQMYV6MBK39QC5PZXHY59C3",
        "workspace": "ws_01J9ZK3P6Q5T8N4M2R7X1V0B9C",
    },
)

In this form, user and organization are target types like any other.

• Node: The userId and organizationId fields shown in the runtime client guide continue to work, but the two forms cannot be mixed in one call. A context with userId alongside workspace matches no targets, logs a warning to your logger, and returns the flag’s default value.
• Python: Target types are the only form. A key like user_id is treated as a custom target type, and userId is ignored because target types are lowercase, so neither matches your user targeting. The client logs a warning to its logger that names the key to use instead, and evaluates the rest of the context.

A context holds at most one resource of each type. To make a decision per workspace, evaluate once per workspace:

const enabledWorkspaces = workspaces.filter((workspace) =>
  client.isEnabled('collaborative-editing', { workspace: { id: workspace.id } }),
);

def enabled_workspace_ids(flags, workspace_ids):
    return [
        workspace_id
        for workspace_id in workspace_ids
        if flags.is_enabled("collaborative-editing", {"workspace": workspace_id})
    ]

Targeting changes reach the runtime client on its next poll, within the polling interval. They are not instant across long-lived server processes.

For each evaluation, the runtime client in @workos-inc/node version 12.0.0 or later, or in the workos Python package version 10.8.0 or later, checks the flag’s configuration in order:

1. If the flag is off in the environment, the result is false.
2. Otherwise, the flag’s rules are checked in order. The first rule that matches a resource in the context, whether an organization, a user, or a custom target, decides the result.
3. If no rule matches, the result is the flag’s default value.

If an earlier rule serves false for a resource, it excludes that resource even when a later rule would include it.

Invalid context never causes an error. The client ignores a type key or ID that fails validation, logs a warning to its logger, and evaluates the rest of the context.

Open the menu at the end of a rule’s row to change it:

• Edit rule adds or removes IDs. The rule type cannot be changed after the rule is created. To target a different type, create another rule.
• Delete rule removes every ID of that type from the environment. The type remains available in the project for other flags and environments.

Removing a target takes effect on the next poll. The resource’s result then comes from the next rule that matches the context, or from the flag’s default value if none does.

Values are validated as entered and are never normalized. A rule type of Workspace is rejected rather than converted to workspace, so a differently cased spelling can never split your targeting across two near-identical types.

• If a flag targeted only at custom targets is missing from the access token, this is expected. The feature_flags claim carries organization and user targeting only. Evaluate custom targets with the runtime client.
• If a rule type is missing from the selector, it may already have a rule in this environment. Edit that rule from its row instead. Otherwise, enter the slug and choose Create new rule type.