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 support@launchdarkly.com

Get Started    

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 sales@launchdarkly.com .

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.

Concepts

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

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:

resource-type/name;tag1,tag2

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:

proj/*

You can also name a specific project by ID:

proj/default

Or all projects tagged mobile:

proj/*;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:

resource-type/name;tag1,tag2:resource-type/name;tag3,tag4,tag5

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

proj/*:env/*:flag/*

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

proj/*:env/*:flag/ops_*

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/*).
  • flag: Feature flags. Feature flags have projects and environments as parent resources (e.g. proj/*:goal/*:flag/*).
  • integration: Integrations. Integrations have no parent resource (e.g. integration/*).
  • webhook: Webhooks. Webooks have no parent resource (e.g. wehbook/*).
  • user: Users. Users have no parent resource (e.g. user/*).

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

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.

Actions

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 createFetaure, 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

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": [
      "proj/*:env/production:flag/*"
    ],
    "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": [
      "proj/*:env/production:flag/*"
    ],
    "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_*:/flag/*"],
    "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:flag/*"],
    "actions": ["updateOn"]
  }
]

Actions reference

Accounts

Action
Description

updateOrganization

Update the organization name

updateSubscription

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

updatePaymentCard

Change the credit card for the account

updateRequireMfa

Change whether multi-factor authentication (MFA) is required for all users on the account

updateAccountToken

Modify account tokens (for the LaunchDarkly REST API)

Members

Action
Description

createMember

Add a new team member to an account

updateRole

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

updateCustomRole

Update a team member's custom roles

deleteMember

Remove a team member from an account

Roles

Action
Description

createRole

Create new custom roles

updatePolicy

Update a custom role's policy

updateName

Update a custom role's name

deleteRole

Delete a custom role

updateMembers

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

Projects

createProject

Create a new project.

deleteProject

Delete a project.

updateProjectName

Rename a project.

Environments

Action
Description

createEnvironment

Create new environments

deleteEnvironment

Delete an existing environment

updateName

Change the name of an environment

updateColor

Change the color swatch for an environment

updateTtl

Change the TTL for an environment

updateApiKey

Reset the API key for an environment

updateMobileKey

Reset the mobile key for an environment

Goals

Action
Description

createGoal

Create goals

deleteGoal

Delete goals

updateKey

Update keys for custom goals

updateName

Update goal names

updateDescription

Update goal descriptions

updateUrls

Update the URLs for a click or page view goal

updateSelector

Update the CSS selector for a click goal

updateOptimizelyGoals

Update Optimizely goals

Feature flags

Action
Description

createFlag

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

deleteFlag

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

updateOn

Trigger the kill switch for a feature

updateIncludeInSnippet

Change whether the feature flag is available to front-end code via the JavaScript SDK . Impacts all environments in a project.

updateName

Change the name of a feature flag. Impacts all environments in a project.

updateDescription

Change the description of a feature flag. Impacts all environments in a project.

updateTemporary

Marks a flag temporary or permanent. Impacts all environments in a project.

updateTags

Update tags associated with a flag. Impacts all environments in a project.

updatePrerequisites

Update flag prerequisites.

updateTargets

Update individual user targeting.

updateRules

Update custom targeting rules.

updateFallthrough

Update the "default" or "fallthrough" rule.

updateOffVariation

Update the variation returned when the kill switch is set to off.

updateMaintainer

Update the flag maintainer. Impacts all environments.

updateAttachedGoals

Update goals attached to a flag (start or stop an A/B testing experiment).

Webhooks

createWebhook

Create a new webhook.

deleteWebhook

Delete a webhook.

updateUrl

Update the URL for a webhook.

updateSecret

Update the webhook secret.

updateStatements

Update the policy filter for a webhook.

updateOn

Turn a webhook on or off.

Integrations

All third-party integrations (e.g. HipChat room notifications) use a shared set of custom role actions.

createIntegration

Create a new third-party integration

deleteIntegration

Delete a third-party integration

updateIntegration

Update a third-party integration

Users

deleteUser

Deletes a user

Custom roles