Using policies
Read time: 3 minutes
Last edited: May 13, 2022
Overview
This topic explains how to write policies for custom roles, integrations access, and Relay Proxy access.
Policies combine resources and actions into a set of statements that define what users can or cannot do in LaunchDarkly. To learn more, read Custom role concepts.
Using the policy algorithm
The algorithm for determining whether a policy allows or denies access is as follows:
- If a statement within a policy explicitly denies access to a resource and action, access is denied. This statement overrides any other statement in the policy that allows access to the resource and action.
- If a statement within a policy explicitly allows access to a resource and action, and no statement denies access, access is allowed.
- If two different policies have conflicting permission levels, the more permissive level of access is applied.
- Any resource or action not specifically included within a policy is denied by default, except the
viewProject
action and thecreateAccessToken
action in policies that use the built-in Reader role as the starting point. To learn more, read Understanding starting roles.
The ability to view and change resources is configured at the project
resource level with the viewProject
action. All custom role recipients can view all projects in your LaunchDarkly instance unless specifically denied.
Custom role recipients can also create access tokens that are limited to their existing permissions. For example, account members with a Reader role can only create tokens with a Reader role, whereas account members with an Admin or Owner role can create tokens with any permission level.
To learn more, read Understanding the minimum required actions for a role.
Statement order does not matter. You can assign multiple custom roles to one member, and each custom role has its own policy.
Permissions are cumulative across roles. If you assign multiple custom roles to a member, and one of those custom roles allows access to a resource, then access is allowed even if other roles deny that access. Adding roles to a user can only increase that user's access.
Understanding policies
Policies are represented as JSON arrays.
Each element in the array is a statement represented as a JSON object with three attributes:
Attribute name | Description |
---|---|
effect | allow or deny . |
actions / notActions | A list of action specifiers defining the actions to which the statement applies or does not apply. |
resources / notResources | A list of resource specifiers defining the resources to which the statement applies or does not apply. |
You can only create a statement using notActions
or notResources
in the advanced editor. To learn more about the advanced editor, read Writing policies in the advanced editor.
Resource specifiers
Resource specifiers allow you to define which resources to allow or deny access to. Three commonly-used resources in custom role policies are projects, environments, and flags.
Here is how to express these resources in code:
proj/KEY
proj/*:env/KEY
proj/*:env/*:flag/KEY
For a full list of available resources, read Using actions.
In these expressions KEY
is the key of the project, environment, or flag. You can use the asterisk *
as a wildcard character to indicate that all resources of that type should be matched. For example, proj/*
indicates all projects within your account.
The colon :
within a policy indicates that the resource after the :
resides within the resource before the :
. For example, proj/account-management:env/production
refers to the production
environment within the account-management
project only. To learn more, read Understanding the resource specifier syntax.
Writing policies in the advanced editor
The LaunchDarkly UI has a structured series of fields you can use to create policies. If you want to write a policy by hand, however, you can use the advanced editor.
To access the advanced editor:
- Navigate to Account settings.
- Click into the Roles tab.
- Click Create role. The "Create custom role" panel appears.
- Click Advanced editor. The advanced editor appears:

When constructing your policy by hand with the advanced editor, make sure to use the resource key, which is case sensitive. If the Production environment of your default project has the key production
then proj/default:env/Production
will not allow actions to be taken in your default project's production environment.
The following example policy denies access to the account-management
project. It also allows all actions on the checkout-flow
flag in all projects and environments.
Here's the example policy:
[{"effect": "deny","actions": ["viewProject"],"notResources": ["proj/account-management"]},{"effect": "allow","actions": ["*"],"resources": ["proj/*:env/*:flag/checkout-flow"]}]
In the next example, the environment key production
represents the account's Production environment. This statement denies the user from modifying any feature flags in production:
[{"effect": "deny","actions": ["*"],"resources": ["proj/*:env/production:flag/*"]}]
You can also name an "inverse" set of resources by using notResources
in a statement. This statement explicitly allows all actions to feature flags across all environments except the production environment.
Here's how:
[{"effect": "allow","actions": ["*"],"notResources": ["proj/*:env/production:flag/*"]}]
For more advanced policy examples, read Example policies and templates.