• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""


    Custom role concepts

    Read time: 4 minutes
    Last edited: Apr 19, 2023


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

    Almost everything in LaunchDarkly is a resource, including:

    • Projects
    • Feature flags
    • Environments
    • Metrics
    • Custom roles

    This graphic shows how resources relate to each other:

    Resource organization diagram.
    Resource organization diagram.

    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.

    Understanding the 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 most resources in LaunchDarkly. Tags do not allow or deny role recipients to do anything, but they 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.

    Tag names can include only letters, numbers, periods ., underscores _, and dashes -.

    The following resources support tags:

    • projects
    • environments
    • segments
    • flags
    • metrics

    Other resources like webhooks and integrations do not support tags.

    To learn more about specific tags, read Using tags.

    You can also use the REST API: Tags