LaunchDarkly Developer Documentation

Get started in under 30 minutes.
LaunchDarkly provides feature flags as a service for Java · Python · Ruby · Go · Node.js · PHP · .NET. Control feature launches -- who sees what and when -- without multiple code deploys. Easy dashboard for phased rollouts, targeting and segmenting.
Need more help? write us at

Get Started    Documentation

Custom roles

Available to enterprise customers

Custom roles are available to customers on our enterprise plans. If you're interested in learning more about our enterprise plans, contact .

LaunchDarkly's basic role-based permission system provides global access control levels for team members based on a set of built-in roles (reader, writer, or admin / owner). Customers on enterprise plans also have access to LaunchDarkly's custom roles system. Custom roles allow you to create flexible policies providing fine-grained access control to everything in LaunchDarkly-- from feature flags to goals, environments and teams. With custom roles, it's possible to enforce access policies that meet your exact workflow needs. For example, you can:

  • Lock your production environment down to a small set of trusted users
  • Distinguish infrastructure-level feature flags (controlled by your devOps team) from experiments (controlled by product management or marketing)
  • Allow QA members to control feature flags on designated QA environments only

Our custom role system is inspired by AWS Identity and Access Management (IAM), so if you're familiar with IAM, you'll see a few similarities.


Custom roles are based around a few core concepts:

  • Resources-- Resources are things that you can control access to. In LaunchDarkly, projects, environments, feature flags, and goals are all examples of resources.
  • Tags-- Tags are identifiers attached to resources that allow you to create ad-hoc groups of resources. For example, you can create a qa tag to mark a set of environments as "QA environments".
  • Actions-- Actions are kinds of modifications that can be performed on resources. Examples include createFeature, deleteFeature, updateName, and updateOn, which correspond to modifications to feature flags.
  • Policies-- A policy is a collection of statements describing allowed (or disallowed) resources and actions.


Resources are concrete things that you can control access to. Almost everything in LaunchDarkly is a resource-- projects, feature flags, environments, and goals are all resources (even custom roles themselves are resources!). When you change a feature flag's rollout rules, or rename an environment, you are accessing a particular resource. LaunchDarkly uses a simple resource specifier syntax to name resources or collections of resources. The basic pattern looks like this:


The resource syntax accepts globs, so you can name collections of resources with *. Tags are also optional-- you can omit the ; if you don't need to specify any tags. For example, here's a resource that names all of the projects in an account:


You can also name a specific project by ID:


Or all projects tagged mobile:


Some resources are scoped within parent resources. For example, goals are scoped within a project, and feature flags are scoped within a project and environment. To name scoped resources, LaunchDarkly uses the following syntax:


For example, the following specifier names all feature flags across all environments:


Here's a resource specifier that names all feature flags whose keys start with 'ops_' across all projects and environments:


For reference, here is the complete list of resource types and their scope levels available in LaunchDarkly:

  • proj: Projects. Projects have no parent resource (e.g. proj/*)
  • env: Environments. Environments have projects as their parent resource (e.g. proj/*:env/*).
  • goal: Goals. Goals have projects at their parent resource (e.g. proj/*:goal/*)
  • member: Team Members. Team members have no parent resource (e.g. member/*).
  • role: Custom roles. Custom roles have no parent resource (e.g. role/*).
  • feature: Feature flags. Feature flags have projects and environments as parent resources (e.g. proj/*:goal/*:feature/*).

There is also a unique resource specifier called acct, which represents modifications to your account itself (including actions like managing your plan).

Finding resource IDs

You can find resource IDs with the Resource finder, which you can access from the policy field in the role editor. All of your environments, members, feature flags, goals and roles will be available.


Tags are simple strings that you can attach to any resource in LaunchDarkly. Tags are useful for grouping resources into a set that you can name in a resource specifier.

Coming soon

Tags are not available yet-- we'll be releasing tag support for all resources soon.

You can add tags to any resource type in LaunchDarkly via the UI or API. As an example, you can create a dev tag for your environments, which you can use in a policy to specify custom rules that only apply to development environments.


Each resource has a set of actions associated with it that represent changes that you can make to that resource. For example, feature flags have actions like createFeature, deleteFeature, updateName, and more.

Action names generally begin with create, update, or delete, making it easy to specify actions in bulk using glob syntax. For example, you can describe all modifications to feature flags with the action specifier update*.

See our Actions reference for a list of the actions available for each resource kind.


Policies combine resources and actions into a set of statements that define what users can or cannot modify in LaunchDarkly. Policies are represented as a JSON array. Each element in the array is a statement, represented as a JSON object with three attributes:

  • effect: Either allow or deny, and defines whether the statement allows or denies access to the named resources and actions.
  • resources / notResources: A list of resource specifiers defining the resources to which the statement applies (or does not apply)
  • actions / notActions: A list of action specifiers defining the actions to which the statement applies (or does not apply).

Here's an example statement:

    "effect": "deny",
    "resources": [
    "actions": [

If the environment ID production represents the account's Production environment, this statement will deny the user from modifying any feature flags in production. You can also name an "inverse" set of resources by using notResources in a statement:

    "effect": "allow",
    "notResources": [
    "actions": [

This statement explicitly allows all actions to feature flags across all environments except the production environment.

The algorithm for determining whether access is allowed or denied by a policy is as follows:

  • If any statement in the policy explicitly denies access to a resource and action, access is denied
  • If a statement in the policy explicitly allows access to a resource and action, and no statement denies access, access is allowed

This means that statement order does not matter.

Note that users can be members of multiple custom roles, and each custom role has its own policy. If any custom role allows access, then access is allowed. This means that adding roles to a user can only increase that user's access.

Example policies

QA team

Members of the QA team may administer environments tagged qa_* and manage flags in environments tagged qa_*.

    "effect": "allow",
    "resources": ["proj/*:env/*;qa_*"],
    "actions": ["*"]
    "effect": "allow",
    "resources": ["proj/*:env/*;qa_*:/feature/*"],
    "actions": ["*"]

Ops team

Members of the ops team may kill switch features on the production environment. They may not change percentage rollouts or targeting rules, or manage any environments or projects.

    "effect": "allow",
    "resources": ["proj/*:env/production:feature/*"],
    "actions": ["updateOn"]

Actions reference




Update the organization name


Change the pricing plan (e.g. Startup / Team / Growth) for the account


Change the credit card for the account




Add a new team member to an account


Update a team member's built-in roles (reader, writer, or admin)


Update a team member's custom roles


Remove a team member from an account




Create new custom roles


Update a custom role's policy


Update a custom role's name


Delete a custom role


Add or remove users from a custom role (equivalent to updateCustomRole on team members).




Create new environments


Delete an existing environment


Change the name of an environment


Change the color swatch for an environment


Change the TTL for an environment


Reset the API key for an environment


Reset the mobile key for an environment




Create goals


Delete goals


Update keys for custom goals


Update goal names


Update goal descriptions


Update the URLs for a click or page view goal


Update the CSS selector for a click goal


Update Optimizely goals




Create a feature. Creating a feature impacts all environments in a project, so users will need permission to create features in all environments.


Delete a feature. Deleting a feature impacts all environments in a project, so users will need permission to delete features in all environments.


Trigger the kill switch for a feature


Change the targeting or rollout rules for a feature


Change whether the feature flag is available on the client-side snippet


Change the name of a feature flag

Custom roles

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.