Create custom role

For the complete documentation index, see llms.txt. For the full documentation snapshot, see llms-full.txt.

Create a new custom role

POST /api/v2/roles

Create custom role

cURL

curl --request POST \
  --url https://app.launchdarkly.com/api/v2/roles \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "basePermissions": "reader",
  "description": "An example role for members of the ops team",
  "key": "role-key-123abc",
  "name": "Ops team",
  "policy": [
    {
      "actions": [
        "updateOn"
      ],
      "effect": "allow",
      "resources": [
        "proj/*:env/production:flag/*"
      ]
    }
  ]
}
'

201

{
  "_id": "1234a56b7c89d012345e678f",
  "_links": {},
  "key": "example-custom-role",
  "name": "Example custom role",
  "policy": [
    {
      "effect": "allow",
      "resources": [
        "proj/*:env/*;qa_*:/flag/*"
      ],
      "notResources": [
        "<string>"
      ],
      "actions": [
        "*"
      ],
      "notActions": [
        "<string>"
      ]
    }
  ],
  "_access": {
    "denied": [
      {
        "action": "<string>",
        "reason": {
          "effect": "allow",
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "notResources": [
            "<string>"
          ],
          "actions": [
            "*"
          ],
          "notActions": [
            "<string>"
          ],
          "role_name": "<string>"
        }
      }
    ],
    "allowed": [
      {
        "action": "<string>",
        "reason": {
          "effect": "allow",
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "notResources": [
            "<string>"
          ],
          "actions": [
            "*"
          ],
          "notActions": [
            "<string>"
          ],
          "role_name": "<string>"
        }
      }
    ]
  },
  "description": "This custom role is just an example",
  "basePermissions": "reader",
  "resourceCategory": "<string>",
  "assignedTo": {
    "membersCount": 123,
    "teamsCount": 123
  },
  "_presetBundleVersion": 123,
  "_presetStatements": [
    {
      "effect": "allow",
      "resources": [
        "proj/*:env/*;qa_*:/flag/*"
      ],
      "notResources": [
        "<string>"
      ],
      "actions": [
        "*"
      ],
      "notActions": [
        "<string>"
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

Body

application/json

name · string · required

A human-friendly name for the custom role

Example:

"Ops team"

key · string · required

The custom role key

Example:

"role-key-123abc"

policy · object[] · required

Resource statements for custom role

Show child attributes

description · string

Description of custom role

Example:

"An example role for members of the ops team"

basePermissions · enum<string>

Base permissions to use for this role. Defaults to no_access (older roles defaulted to reader). Recommended to set this to no_access in all cases.

Available options: reader, no_access

Example:

"reader"

resourceCategory · string

The category of resources this role is intended to manage. Can be organization, project, or any. This field is immutable.

Response

201

application/json

Custom role response

_id · string · required

The ID of the custom role

Example:

"1234a56b7c89d012345e678f"

_links · object · required

The location and content type of related resources

Show child attributes

key · string · required

The key of the custom role

Example:

"example-custom-role"

name · string · required

The name of the custom role

Example:

"Example custom role"

policy · object[] · required

An array of the policies that comprise this custom role

Show child attributes

_access · object

Details on the allowed and denied actions for this custom role

Show child attributes

description · string

The description of the custom role

Example:

"This custom role is just an example"

basePermissions · string

Base permissions to use for this role. Defaults to no_access (older roles defaulted to reader). Recommended to set this to no_access in all cases.

Example:

"reader"

resourceCategory · string

The category of resources this role is intended to manage. Can be organization, project, or any. Once set, this field cannot be changed.

assignedTo · object

The number of teams and members this role is assigned to

Show child attributes

_presetBundleVersion · integer

If created from a preset, the preset bundle version

_presetStatements · object[]

If created from a preset, the read-only statements copied from the preset

Show child attributes