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
Security:
ApiKey (readwrite)
Responses
200

Custom roles collection response.

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/roles
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/roles \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "_links": {
    },
  • "items": [
    ]
}

Create custom role

Create a new custom role

Request
Security:
ApiKey (readwrite)
Request Body schema: application/json
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
{
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "policy": [
    ],
  • "basePermissions": "string"
}
Response samples
application/json
{
  • "_id": "string",
  • "_links": {
    },
  • "_access": {
    },
  • "description": "string",
  • "key": "string",
  • "name": "string",
  • "policy": [
    ],
  • "basePermissions": "string"
}

Get custom role

Get a single custom role by key or ID

Request
Security:
ApiKey (readwrite)
path Parameters
key
required
string <string>

The custom role's 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/{key}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/roles/:key \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "_id": "string",
  • "_links": {
    },
  • "_access": {
    },
  • "description": "string",
  • "key": "string",
  • "name": "string",
  • "policy": [
    ],
  • "basePermissions": "string"
}

Update custom role

Update a single custom role. The request must be a valid JSON Patch document describing the changes to be made to the custom role.

Request
Security:
ApiKey (readwrite)
path Parameters
key
required
string <string>

The key of the custom role to update

Request Body schema: application/json
required
Array of objects (JSONPatch)
comment
string
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/{key}
Request samples
application/json
{
  • "patch": [
    ],
  • "comment": "string"
}
Response samples
application/json
{
  • "_id": "string",
  • "_links": {
    },
  • "_access": {
    },
  • "description": "string",
  • "key": "string",
  • "name": "string",
  • "policy": [
    ],
  • "basePermissions": "string"
}

Delete custom role

Delete a custom role by key

Request
Security:
ApiKey (readwrite)
path Parameters
key
required
string <string>

The key of the custom role to delete

Responses
204

Action succeeded

401

Invalid access token

404

Invalid resource identifier

429

Rate limited

delete/api/v2/roles/{key}
Request samples
curl -i -X DELETE \
  https://app.launchdarkly.com/api/v2/roles/:key \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "code": "unauthorized",
  • "message": "invalid key"
}