> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LaunchDarkly

> Connect LaunchDarkly to Serval to list projects, inspect and toggle feature flags, browse environments, and review audit history through Serval workflows.

## 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

| Capability                 | Description                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| List LaunchDarkly Projects | List all projects in your LaunchDarkly account, with project keys, names, and metadata.                           |
| List Feature Flags         | List the feature flags in a project, with keys, names, descriptions, and current status.                          |
| Get Feature Flag Details   | Get full detail on a specific flag, including its variations, targeting rules, and per-environment configuration. |
| Toggle Feature Flag        | Turn a feature flag on or off in a specific environment. Runs require approval by default.                        |
| List Environments          | List all environments for a project, with keys, names, and configuration.                                         |
| List Audit Log Entries     | Retrieve the 20 most recent audit log entries showing who changed what and when.                                  |

Anything defined in the [LaunchDarkly API](https://launchdarkly.com/docs/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](https://launchdarkly.com/docs/home/account/api-create); for the difference between token types, see the [API access tokens overview](https://launchdarkly.com/docs/home/account/api).

<Steps>
  <Step title="Open Authorization settings">
    In LaunchDarkly, click the gear icon in the left sidebar to open Organization settings, then click **Authorization**.
  </Step>

  <Step title="Create a token">
    In the **Access tokens** section, click **Create token**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the token">
    Click **Save token**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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).
</Tip>

<Note>
  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.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the LaunchDarkly connect form">
    In Serval, find the LaunchDarkly integration and open its connect form.
  </Step>

  <Step title="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".
  </Step>

  <Step title="Submit">
    Submit the form. If the connection cannot be created you may see "Failed to connect service" or "Failed to install integration".
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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:

| Health check                 | What it verifies                                            | Success message                                                              | Failure message                                                                                                               |
| ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Test LaunchDarkly Connection | Basic connectivity and authentication by fetching projects. | "Successfully connected to LaunchDarkly"                                     | "Unable to connect to LaunchDarkly. Please verify your API access token is correct and has not expired."                      |
| List Feature Flags           | Permission to read feature flags in your first project.     | "Successfully listed feature flags from project "\[project key]""            | "Unable to list feature flags from LaunchDarkly. Please verify your access token has read permissions for feature flags."     |
| List Environments            | Permission to read environments in your first project.      | "Successfully listed \[number] environment(s) from project "\[project key]"" | "Unable to list environments from LaunchDarkly. Please verify your access token has read permissions for environments."       |
| List Account Members         | Permission to read account members.                         | "Successfully listed account members (\[number] returned)"                   | "Unable to list account members from LaunchDarkly. Please verify your access token has read permissions for account members." |

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".

<Tip>
  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).
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The form accepted my token, but health checks fail">
    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.
  </Accordion>

  <Accordion title="Paste the token exactly - do not add Bearer or any prefix">
    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.
  </Accordion>

  <Accordion title="The connection broke after I edited the settings">
    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.
  </Accordion>

  <Accordion title="Toggle Feature Flag runs wait for approval">
    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.
  </Accordion>

  <Accordion title="Federal and EU LaunchDarkly instances are not supported">
    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.
  </Accordion>

  <Accordion title="A personal token stops working when its creator leaves">
    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.
  </Accordion>

  <Accordion title="Flag updates use the JSON Patch format, not semantic patch">
    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.
  </Accordion>

  <Accordion title="Search filters behave differently across LaunchDarkly endpoints">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your LaunchDarkly integration.