Target Users

How it Works

• FlagPilot never knows who your users are. We do not sync or import your user databases.
• Only opaque IDs are stored. We match against plain strings that you provide.
• User IDs come directly from your application. You pass them dynamically during flag evaluation.

Quick Start

Pass the user ID during flag evaluation. FlagPilot checks the Target Users list before applying any rollout percentage:

const enabled = await flagpilot.evaluate("checkout-v2", {
  userId: currentUser.id
});

Use this same userId when adding Target Users inside the dashboard. If the ID is in the target list, the flag resolves to true immediately.

Architecture

The evaluation chain runs entirely within the SDK — no network call is made at request time:

Complete Integration Example

A full example showing user authentication, flag evaluation, and conditional rendering in a Next.js Server Component:

import { auth } from '@/lib/auth';
import { FlagPilot } from '@flagpilot/node';

const FlagPilotClient = new FlagPilot({
  apiKey: process.env.FLAGPILOT_SECRET_KEY,
  environment: 'production',
});

export default async function CheckoutPage() {
  const currentUser = await auth();

  const enabled = await FlagPilotClient.evaluate('checkout-v2', {
    userId: currentUser.id,
  });

  return enabled ? <CheckoutV2 /> : <CheckoutV1 />;
}

Why use Target Users?

• Yourself — Validate code logic directly in production without touching other users.
• Your QA Team — Run verification flows on the live environment before any public launch.
• Internal employees — Dogfood the feature company-wide before opening it to customers.
• Selected beta customers — Collect early feedback from trusted partners or pilot accounts.
• Customer previews — Let a specific enterprise customer preview features under NDA.

Integration Guide

REST API Examples

POST /v1/flags/checkout-v2/users
Authorization: Bearer fk_secret_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "userId": "user_123"
}

GET /v1/flags/checkout-v2/users
Authorization: Bearer fk_secret_xxxxxxxxxxxxxxxx

DELETE /v1/flags/checkout-v2/users/user_123
Authorization: Bearer fk_secret_xxxxxxxxxxxxxxxx

curl -X POST https://api.tryflagpilot.com/v1/flags/checkout-v2/users \
  -H "Authorization: Bearer fk_secret_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123"}'

Evaluation Responses

{
  "enabled": true,
  "reason": "target_user"
}

{
  "enabled": true,
  "reason": "rollout_percentage"
}

Audit Logging

Every target user modification generates an immutable audit log entry:

Performance Validation

Security Best Practices

When to Use Target Users

Use Target Users for QA teams, developer accounts, or a controlled alpha test. For general canary releases or scaling to thousands of users, use a **Percentage Rollout** instead.

Best Practices

• ✓Clean up targeted users after graduating features to 100%.
• ✓Use opaque identifiers (like UUIDs) rather than emails or names.
• ✓Separate production and staging targeting criteria.

FAQ