> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plerion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete a custom role

> Deletes a custom role that nobody holds. While a user or user group holds it the answer is 409 `RoleHasAssignments`; while a tenant API key holds it, 409 `RoleHasApiKeys`. A built-in role answers 400 `BuiltinRoleImmutable`. Requires the readWrite access level.




## OpenAPI

````yaml /api-reference/organization-openapi.yaml delete /v1/organization/roles/{roleId}
openapi: 3.1.0
info:
  title: Plerion organization API
  version: v1
  termsOfService: https://www.plerion.com/terms-and-conditions
  contact:
    name: Plerion Pty Ltd
    url: https://www.plerion.com/contact-us
    email: support@plerion.com
  license:
    name: Plerion Use License
    url: https://www.plerion.com/terms-and-conditions
  description: |-
    The Plerion organization API manages roles and role assignments for a
    whole organization: the roles that exist, the permissions each one
    grants, and which users and user groups hold them. It covers the same
    lifecycle as the roles and user access pages of the Plerion app, so an
    automation can grant and revoke access without a person signing in.

    Requests are authenticated with a Plerion organization API key sent as
    a bearer token. The organization is resolved from the key, so no request
    names an organization. Reads work with a key of either access level;
    writes need a key with the readWrite access level.

    List responses are `{ "data": [...], "meta": { "cursor": ... } }`. Pass
    `meta.cursor` back as the `cursor` query parameter to fetch the next
    page; it is `null` on the last page. Single objects are `{ "data": ... }`.
    Deletes answer 204 with no body. Errors are
    `{ "errors": [{ "code": ..., "message": ... }] }`.
servers:
  - url: https://{region}.api.plerion.com
    description: Production API server - Select your preferred region
    variables:
      region:
        default: au
        enum:
          - au
          - sg1
          - in1
          - us1
security:
  - organizationApiKey: []
tags:
  - name: Roles
    x-displayName: Roles
    description: >-
      Built-in and custom roles. A built-in role's permissions are fixed and
      shown for reference; a custom role's permissions name actions or action
      groups from the permission catalog, optionally narrowed to specific
      integrations. Writes need an organization API key with the readWrite
      access level.
  - name: Role assignments
    x-displayName: Role assignments
    description: >-
      Which users and user groups hold which roles. A tenant-scoped role applies
      to one tenant; an organization-scoped role applies everywhere. Writes need
      an organization API key with the readWrite access level.
  - name: Permission catalog
    x-displayName: Permission catalog
    description: >-
      The actions and action groups a role's permissions may name, with the
      level and resource type of each action. Read this before writing a role.
paths:
  /v1/organization/roles/{roleId}:
    parameters:
      - $ref: '#/components/parameters/roleId'
    delete:
      tags:
        - Roles
      summary: Delete a custom role
      description: >
        Deletes a custom role that nobody holds. While a user or user group
        holds it the answer is 409 `RoleHasAssignments`; while a tenant API key
        holds it, 409 `RoleHasApiKeys`. A built-in role answers 400
        `BuiltinRoleImmutable`. Requires the readWrite access level.
      operationId: deleteOrganizationRole
      responses:
        '204':
          description: Deleted.
        '400':
          $ref: '#/components/responses/DeleteRoleBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  parameters:
    roleId:
      name: roleId
      in: path
      required: true
      description: The role id, built-in or custom.
      schema:
        type: string
        format: uuid
  responses:
    DeleteRoleBadRequest:
      description: |
        The role is built in (`BuiltinRoleImmutable`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: BuiltinRoleImmutable
                message: built-in roles cannot be deleted
    Unauthorized:
      description: The organization API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The key has the read access level and the operation writes, or the key
        is a tenant API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >
        No such role, user, tenant, assignment or principal kind. Codes include
        `RoleNotFound`, `UserNotFound`, `TenantNotFound`, `AssignmentNotFound`
        and `PrincipalKindNotFound`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: RoleNotFound
                message: role not found
    Conflict:
      description: >
        The change conflicts with current state. Codes include
        `AssignmentAlreadyExists`, `RoleHasAssignments`, `RoleHasApiKeys`,
        `BreakGlassRolesLocked` and `UserRecordChanged`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: RoleHasAssignments
                message: role has active assignments; revoke them first
  schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
                description: Present on validation errors.
            required:
              - code
              - message
      required:
        - errors
  securitySchemes:
    organizationApiKey:
      type: http
      scheme: bearer
      description: >
        Plerion organization API key (plerion_oak_…), created by an organization
        admin in the Plerion app. GET operations work with a key of either
        access level; POST, PUT and DELETE require the readWrite access level.

````