Skip to main content

​
About LaunchDarkly

LaunchDarkly is a feature management platform for feature flags, targeting rules, environments, and experimentation. Serval connects to your LaunchDarkly account with a single API access token, so workflows can look up projects and flags, toggle flags, and pull audit history on your behalf. The token’s role on the LaunchDarkly side fully determines what Serval can read and write - Serval requests no permissions of its own, and it only ever sends the token to LaunchDarkly’s standard API host, app.launchdarkly.com. Authentication: API access token (a personal or service access token created in LaunchDarkly’s Authorization settings). Data sync: On demand only. Serval reads or writes LaunchDarkly data while a workflow step is running. There is no background sync and no webhooks.

​
What the LaunchDarkly integration enables

Anything defined in the LaunchDarkly API can be accessed through Serval.

​
Get your credentials

Serval needs one credential: a LaunchDarkly API access token. You can use a personal access token (its permissions follow the member who created it) or a service access token (fixed permissions that survive membership changes, but requires a LaunchDarkly Enterprise plan). LaunchDarkly’s official guide is Creating API access tokens; for the difference between token types, see the API access tokens overview.
1

Open Authorization settings

In LaunchDarkly, click the gear icon in the left sidebar to open Organization settings, then click Authorization.
2

Create a token

In the Access tokens section, click Create token.
3

Name it and assign a role

Give the token a human-readable name and assign a Role (Reader, Writer, Admin, Owner, a custom role, or an inline policy). Check This is a service token if you want a service token (Enterprise only) whose permissions do not change with the creating member.
4

Save the token

Click Save token.
5

Copy it immediately

Copy the token right away - it is visible exactly once. If you leave or refresh the page it is obscured permanently and you must create a new one.
For Serval’s health checks to pass, the token needs at minimum read access to projects. Add read access to feature flags, environments, and account members to satisfy the remaining checks - a Reader role covers all of these. If you plan to use the Toggle Feature Flag workflow, the token also needs write access to flags (for example a Writer role or an equivalent custom role).
For a durable team connection, prefer a service token where available. A personal token’s permissions follow the member who created it and stop working if that member leaves your LaunchDarkly account.

​
Connect in Serval

1

Open the LaunchDarkly connect form

In Serval, find the LaunchDarkly integration and open its connect form.
2

Paste your token

Paste the token into the API Access Token field (required) - “A personal or service access token from your LaunchDarkly Authorization settings”. Paste it exactly as LaunchDarkly displayed it, with nothing added before or after. Leaving the field empty shows “This field is required”.
3

Submit

Submit the form. If the connection cannot be created you may see “Failed to connect service” or “Failed to install integration”.
Serval does not contact LaunchDarkly when you submit the form, so an invalid or expired token will still connect “successfully”. Always check the health check results after connecting - when you connect from an application’s setup form, Serval runs the health checks automatically right after the connection saves.
When you later edit the connection settings, the saved token displays as an obfuscated value (bullets plus the last 4 characters) next to a pencil icon - or a Replace button if you are in the configure dialog - and the field shows the placeholder “Enter new value” once you start replacing it. Do not save the settings form without pasting the complete token again - whenever you edit the connection (for example to rotate the token), always re-enter the full token before saving, then re-run health checks.

​
Verifying the connection

Serval runs four health checks against your LaunchDarkly account: If your account has no projects yet, the flag and environment checks still pass with “Connected to LaunchDarkly but no projects found to list flags from” and “Connected to LaunchDarkly but no projects found to list environments from”.
All four health checks are read-only, so they can be fully green while the Toggle Feature Flag workflow still fails. If toggling a flag returns a permission error, your token has read access but lacks write access to flags - recreate or re-role the token with write permission (for example Writer).

​
Gotchas and troubleshooting

The connect form accepts any non-empty value without contacting LaunchDarkly, so a typo’d, expired, or revoked token only surfaces when health checks run. If “Test LaunchDarkly Connection” fails, create a fresh token in LaunchDarkly’s Authorization settings and reconnect. Also confirm the token has at least read access to projects - that is the minimum for the connection test.
Serval sends the stored token to LaunchDarkly exactly as you entered it, which is what LaunchDarkly expects. Do not type “Bearer ”, “api-key ”, or anything else in front of the token in the form - any added text makes every request fail as unauthorized.
When updating the connection, always paste the complete token again before saving - never save the settings form with the token field untouched or cleared. If the connection stops working after an edit, re-enter a valid token and re-run health checks.
The prebuilt Toggle Feature Flag workflow installs with installer approval required by default, so flag toggles are gated behind the installer’s approval out of the box. The five read-only prebuilt workflows (list projects, list flags, get flag details, list environments, list audit log entries) install with no approval required.
The integration only reaches LaunchDarkly’s standard instance at app.launchdarkly.com. Accounts on LaunchDarkly’s federal instance (app.launchdarkly.us) or EU endpoints cannot connect through this integration.
A personal token’s permissions follow the member who created it and die with that member’s account. A service token’s permissions are fixed at creation and survive membership changes, but service tokens require LaunchDarkly Enterprise. Prefer a service token for a durable team connection where available.
If your team builds custom workflows that modify flags through the generic LaunchDarkly API action, those updates must use LaunchDarkly’s JSON Patch format (a list of operations, optionally with a comment attached). LaunchDarkly’s alternative “semantic patch” format will not work through this integration.
The feature flag list supports fuzzy search across flag key, name, and description - the search term should not be wrapped in quotes. Other areas of the LaunchDarkly API, such as segments, do not support that search filter at all; workflows there must page through results and filter afterward. Do not assume one area’s filter format works in another.
Need help? Contact support@serval.com for assistance with your LaunchDarkly integration.