No results for ""
  • Home
  • API docs


Custom role concepts

Read time: 5 minutes
Last edited: May 01, 2024


This topic is an overview of concepts that are important to creating custom roles. You can create powerful custom roles by using LaunchDarkly's built-in advanced editor.

To write your own custom role, you'll need to understand the following key concepts:

  • Resources
  • Actions
  • Roles
  • Policies
  • Tags
  • Property-based selectors
The advanced editor is powerful

The advanced editor can cause large permissions changes to sensitive or confidential resources. If you use the advanced editor incorrectly, it is possible to disable your LaunchDarkly project, lock yourself out of your account, or cause other irrevocable changes.

It is critically important that you read all the documentation in the "Custom roles" section thoroughly before you use the advanced editor to create or modify any custom roles.

To learn more, read Using the advanced editor.


When you write a custom role, you specify resources that the role can or cannot access.

LaunchDarkly has many kinds of resources, such as:

  • Projects
  • Environments
  • Feature flags
  • Metrics
  • Experiments
  • Context kinds
  • Segments

For a full list of LaunchDarkly resources, read About resource types and scopes.

Understanding permissions for accessing resources

The default permission level of any account member in LaunchDarkly is the built-in Reader role. This is the role that is assigned to new account members by default.

To give an account member the ability to modify resources in LaunchDarkly, you must assign them a different role: Writer, Admin, Owner, or a custom role with the appropriate actions.

To prevent an account member from accessing any part of the LaunchDarkly platform, you can assign them the No access role. This role is for members who shouldn't be able to view or modify anything until you give them access to specific areas of LaunchDarkly.

To learn more about specific resources, read Using resources.


Each resource has a set of actions associated with it. By granting a custom role resource-specific actions, you allow or forbid members with that custom role to do things to that resource. For example, you can allow a custom role the ability to delete a project.

To learn more about specific actions, read Using actions.


When you create a role, you specify the role policy using either the Resource finder or the Advanced editor.

There are two ways to approach writing your own custom roles:

  • Allow view-only access by default, then strategically add and deny additional actions as needed. A custom role that has no role policy specified, and the By default, members can view all LaunchDarkly content box checked, allows view access to all resources. You must explicitly grant access to a resource for a member to edit it.
  • Deny all actions by default, then strategically allow actions as needed. A custom role that has no role policy specified, and the By default, members can view all LaunchDarkly content box unchecked, denies all access to all resources. You must explicitly grant access to a resource for a member to view or edit it.

For additional discussion on how to decide between these approaches, read the Creating custom roles guide.

Minimum required actions for a role

As a default state, a blank custom role allows only view access to all resources. You must explicitly grant access to a resource for a member to edit it.

The two exceptions are:

  • The viewProject action: The ability to view and change resources is configured at the project resource level with the viewProject action.
  • The createAccessToken action: The ability to create personal access tokens is configured at the members resource level with the createAccessToken action. The ability to create service access tokens is configured at the top resource level with the createAccessToken action.

To learn more about configuring the viewProject action, read Creating private projects with custom roles.

Viewing permissions are not the same as permissions that let a member modify the resources they can view. For example, being able to view a project does not mean a role recipient can take action on that project. A role recipient cannot take any actions on the project unless you explicitly permit them.


Policies combine resources and actions into a set of statements that define what members can or cannot do in LaunchDarkly.

You use LaunchDarkly's advanced editor to build custom roles by writing combinations of resources and actions the role is allowed to or forbidden from taking on them.

Permissions are cumulative

When a team or account member has two or more custom roles with conflicting permission levels, the more permissive level of access is applied. For example, if a team has one custom role that allows access to a resource, and a member of that team has another custom role that restricts access to a resource, the member is allowed access.

Policies are represented as JSON arrays. They require you to use project and environment keys, not names.

Each element in the array is a statement represented as a JSON object with three attributes:

  • effect
  • actions / notActions
  • resources / notResources

The example below shows a policy that allows the role recipient to perform all actions on a flag called exampleFlag:

"effect": "allow",
"actions": ["*"],
"resources": ["proj/*:env/*:flag/exampleFlag"]

To learn more about specific policies, read Using policies.


Tags are simple strings that you can attach to certain resources in LaunchDarkly, including projects, environments, segments, flags, and metrics. Tags are useful for grouping resources into a set that you can name in a resource specifier. For example, you can create a dev tag for your environments and use it in a policy to specify custom rules that only apply to development environments.

To learn more about tags and custom roles, read Using tags.

You can also use the REST API: Tags

Property-based selectors

All resources, such as projects, environments, and flags, have various properties. Some resource properties are available to use in a resource specifier. You can select for resources whose properties match a particular value. For example, you can create policies that apply to all environments that are marked as critical.

To view example custom roles that use property-based selectors, read Example policies and templates.