launchdarkly Custom Roles API

openapi: 3.2.0
info:
  title: LaunchDarkly REST Custom Roles API
  description: The LaunchDarkly REST API provides programmatic access to the full LaunchDarkly feature management platform. Developers can create, update, and manage feature flags, targeting rules, user segments, projects, environments, and team members. The API also supports scheduled flag changes, release pipelines, experimentation, approval workflows, and webhook integrations. Authentication is handled via personal or service access tokens, and the API follows a versioned scheme with the current default version being 20240415.
  version: '20240415'
  contact:
    name: LaunchDarkly Support
    url: https://support.launchdarkly.com
  termsOfService: https://launchdarkly.com/policies/terms-of-service
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://app.launchdarkly.com/api/v2
  description: LaunchDarkly Production API
security:
- bearerAuth: []
tags:
- name: Custom Roles
  description: Define custom roles with fine-grained permissions using resource specifiers and actions.
paths:
  /roles:
    get:
      operationId: listCustomRoles
      summary: List custom roles
      description: Returns a list of all custom roles defined in the LaunchDarkly account.
      tags:
      - Custom Roles
      responses:
        '200':
          description: Successful response containing a list of custom roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRoles'
        '401':
          description: Unauthorized. Invalid or missing access token.
    post:
      operationId: createCustomRole
      summary: Create a custom role
      description: Creates a new custom role with the specified permissions policy.
      tags:
      - Custom Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomRoleBody'
      responses:
        '201':
          description: Custom role created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRole'
        '400':
          description: Invalid request body.
        '401':
          description: Unauthorized. Invalid or missing access token.
        '409':
          description: A custom role with the given key already exists.
components:
  schemas:
    Statement:
      type: object
      description: A policy statement controlling resource access or event filtering.
      properties:
        effect:
          type: string
          description: Whether this statement allows or denies the action.
          enum:
          - allow
          - deny
        resources:
          type: array
          description: Resource specifiers this statement applies to.
          items:
            type: string
        notResources:
          type: array
          description: Resource specifiers this statement does not apply to.
          items:
            type: string
        actions:
          type: array
          description: The actions this statement applies to.
          items:
            type: string
        notActions:
          type: array
          description: The actions this statement does not apply to.
          items:
            type: string
    Links:
      type: object
      description: HATEOAS links for navigating related resources.
      properties:
        self:
          type: object
          description: A link to this resource.
          properties:
            href:
              type: string
              description: The URL of this resource.
            type:
              type: string
              description: The media type.
      additionalProperties:
        type: object
        properties:
          href:
            type: string
            description: The URL of the linked resource.
          type:
            type: string
            description: The media type.
    CustomRoleBody:
      type: object
      description: The request body for creating a custom role.
      required:
      - name
      - key
      - policy
      properties:
        name:
          type: string
          description: The human-readable name of the custom role.
        key:
          type: string
          description: The custom role key.
        description:
          type: string
          description: A description of the custom role.
        policy:
          type: array
          description: The policy statements defining permissions.
          items:
            $ref: '#/components/schemas/Statement'
    CustomRole:
      type: object
      description: A custom role with fine-grained permissions.
      properties:
        _id:
          type: string
          description: The unique identifier of this custom role.
        key:
          type: string
          description: The custom role key.
        name:
          type: string
          description: The human-readable name of this custom role.
        description:
          type: string
          description: A description of this custom role.
        policy:
          type: array
          description: The policy statements defining permissions.
          items:
            $ref: '#/components/schemas/Statement'
        _links:
          $ref: '#/components/schemas/Links'
    CustomRoles:
      type: object
      description: A collection of custom roles.
      properties:
        items:
          type: array
          description: The list of custom roles.
          items:
            $ref: '#/components/schemas/CustomRole'
        _links:
          $ref: '#/components/schemas/Links'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: LaunchDarkly API access token. Create personal or service tokens in the LaunchDarkly dashboard under Account Settings.
externalDocs:
  description: LaunchDarkly API Documentation
  url: https://apidocs.launchdarkly.com/