Custom roles

Custom roles is an Enterprise feature

Custom roles is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

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.

The custom roles API allows you to create, update and delete custom roles. You can also use the API to list all of your custom roles or get a custom role by ID.

For more information about custom roles and the syntax for custom role policies, read the product documentation for Custom roles.

List custom roles

Get a complete list of custom roles. Custom roles let you 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. 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.

Request
query Parameters
limit
integer <int64>

The maximum number of custom roles to return. Defaults to 20.

offset
integer <int64>

Where to start in the list. Defaults to 0. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

Responses
200

Custom roles collection response

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/roles
Request samples 
Response samples 
application/json
{
  • "_links": {
    },
  • "items": [
    ],
  • "totalCount": 0
}
Create custom role
Create a new custom role


Request 
Request Body schema: application/json
required
name
required
string
A human-friendly name for the custom role


 
key
required
string
The custom role key


 
description
string
Description of custom role


 
required
Array of objects (StatementPostList) 
 
basePermissions
string (RoleType) 
 
Responses 
201
Custom role response


400
Invalid request


401
Invalid access token


403
Forbidden


409
Status conflict


429
Rate limited


post/api/v2/roles
Request samples 
application/json
{
  • "basePermissions": "reader",
  • "description": "An example role for members of the ops team",
  • "key": "role-key-123abc",
  • "name": "Ops team",
  • "policy": [
    ]
}
Response samples 
application/json
{
  • "_id": "1234a56b7c89d012345e678f",
  • "_links": {
    },
  • "_access": {
    },
  • "description": "This custom role is just an example",
  • "key": "example-custom-role",
  • "name": "Example custom role",
  • "policy": [
    ],
  • "basePermissions": "string"
}
Get custom role
Get a single custom role by key or ID


Request 
path Parameters
customRoleKey
required
string <string> 
The custom role key or ID


 
Responses 
200
Custom role response


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


get/api/v2/roles/{customRoleKey}
Request samples 
Response samples 
application/json
{
  • "_id": "1234a56b7c89d012345e678f",
  • "_links": {
    },
  • "_access": {
    },
  • "description": "This custom role is just an example",
  • "key": "example-custom-role",
  • "name": "Example custom role",
  • "policy": [
    ],
  • "basePermissions": "string"
}
Update custom role
Update a single custom role. Updating a custom role uses a JSON patch or JSON merge patch representation of the desired changes. To learn more, read Updates.

To add an element to the policy array, set the path to /policy and then append /<array index>. Use /0 to add to the beginning of the array. Use /- to add to the end of the array.


Request 
path Parameters
customRoleKey
required
string <string> 
The custom role key


 
Request Body schema: application/json
required
required
Array of objects (JSONPatch) 
 
comment
string
Optional comment


 
Responses 
200
Custom role response


400
Invalid request


401
Invalid access token


404
Invalid resource identifier


409
Status conflict


429
Rate limited


patch/api/v2/roles/{customRoleKey}
Request samples 
application/json
{
  • "patch": [
    ]
}
Response samples 
application/json
{
  • "_id": "1234a56b7c89d012345e678f",
  • "_links": {
    },
  • "_access": {
    },
  • "description": "This custom role is just an example",
  • "key": "example-custom-role",
  • "name": "Example custom role",
  • "policy": [
    ],
  • "basePermissions": "string"
}
Delete custom role
Delete a custom role by key


Request 
path Parameters
customRoleKey
required
string <string> 
The custom role key


 
Responses 
204
Action succeeded


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


delete/api/v2/roles/{customRoleKey}
Request samples 
Response samples 
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}
➔ Next to Data Export destinations