LaunchDarkly
Sync audience segments to LaunchDarkly for feature flag targeting. SignalSmith pushes context keys into LaunchDarkly segments, enabling you to target feature flags and experiments based on your warehouse data.
Prerequisites
- A LaunchDarkly account with API access
- A LaunchDarkly access token with Writer permissions
- An existing segment in your LaunchDarkly project
Authentication
LaunchDarkly uses Access Token authentication.
- In LaunchDarkly, navigate to Account settings > Authorization
- Click Create token
- Give the token a descriptive name and select Writer role (or a custom role with segment write permissions)
- Copy the access token
- Paste it into the Access Token field in SignalSmith
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| API Instance | Select | Yes | LaunchDarkly instance: US (Commercial), EU, or Federal |
| Project Key | Text | Yes | The key of your LaunchDarkly project |
| Environment Key | Text | Yes | The environment to sync segments to (e.g., production, staging) |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Segment Key | Text | Yes | The key of the segment to sync context keys to |
| Context Kind | Text | No | The context kind for targeting. Default: user |
Supported Operations
Sync Modes
LaunchDarkly segments are list-based and do not support record-level sync modes.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
Features
- Field Mapping: No (segments only use context keys)
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| context_key | The unique context key identifying each user or entity in LaunchDarkly |
Default Destination Fields
context_key
How It Works
- SignalSmith extracts context keys from your model or audience
- Keys are sent to the LaunchDarkly Segments API using semantic patch operations
- For Add mode, keys are added to the segment’s included targets
- For Remove mode, keys are removed from the segment’s included targets
- For Mirror mode, added/changed keys are included and removed keys are excluded — keeping the segment in sync with your warehouse
Context keys are sent in batches of up to 1,500 per API request to respect LaunchDarkly’s API limits.
Rate Limits
LaunchDarkly enforces rate limits across all API tokens on your account. Limits reset every 10 seconds. SignalSmith automatically handles rate limiting with exponential backoff and respects Retry-After headers.
Best Practices
- Use Mirror mode to keep segments fully in sync with your warehouse data
- Create dedicated access tokens for SignalSmith with minimal required permissions
- Use meaningful segment keys that reflect the audience purpose (e.g.,
beta-users,high-value-customers) - Start with a non-production environment to verify sync behavior before targeting production
Troubleshooting
Authentication failed
Verify your access token is valid and has Writer permissions. Access tokens can be found in Account settings > Authorization. Note that SDK keys, mobile keys, and client-side IDs cannot access the REST API.
Segment not found
Ensure the segment key, project key, and environment key are correct. The segment must already exist in LaunchDarkly — SignalSmith does not create segments automatically.
Rate limit errors
LaunchDarkly rate limits are shared across all tokens on your account. If other integrations or team members are making heavy API use, you may see rate limit errors. SignalSmith retries automatically, but persistent issues may require reducing concurrent API usage.
Context keys not appearing in targeting
Verify the context kind matches what your LaunchDarkly SDKs send. The default context kind is user, but if your application uses custom context kinds, you must configure the same kind in SignalSmith.
Wrong API instance
If you see connection errors, verify you selected the correct API instance. US accounts use app.launchdarkly.com, EU accounts use app.eu.launchdarkly.com, and Federal accounts use app.launchdarkly.us.
Mirror mode removing unexpected users
Mirror mode synchronizes the segment to exactly match your audience. Users not in the current audience will be removed from the segment’s included targets. If you only want to add users without removing existing ones, use Add mode instead.