---
title: "deleteRole"
method: DELETE
path: "/v1/permissions/roles/{roleId}"
tags: ["Roles"]
---

# deleteRole

`DELETE /v1/permissions/roles/{roleId}`

Delete role by id

## Path parameters

- `roleId` string, required — Format: <organization_id>:<slug>

## Response `200`

ok

- union
  - UserRole — A standard user role. Must be explicitly assigned to users.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'user_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition.
            - `attribute` string, required
            - `operation` 'not_equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'equals_current_user', required
          - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'not_equals_current_user', required
    - `parent_role` string — Optional parent role that this role inherits from. Must be an `org_role` or `share_role`.
    - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization.
  - OrgRole — A role automatically applied to all users in an organization.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'org_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition.
            - `attribute` string, required
            - `operation` 'not_equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'equals_current_user', required
          - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'not_equals_current_user', required
    - `pricing_tier` string — The pricing tier of the organization this root role is based on
  - ShareRole — A role that can be assigned to users in other organizations for sharing purposes.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'share_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition.
            - `attribute` string, required
            - `operation` 'not_equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'equals_current_user', required
          - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'not_equals_current_user', required
  - PartnerRole — A role that appears in another organization's role list that can be assigned but not modified by the partner organization.
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'partner_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition.
            - `attribute` string, required
            - `operation` 'not_equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'equals_current_user', required
          - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'not_equals_current_user', required
    - `partner_org_id` string — Id of an organization
    - `vendor_enforced_user_limit` integer — Maximum number of users that can be assigned this role (vendor-enforced limit, can only be set via internal auth)
    - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization.
  - PortalRole — A role that is applied to end customers and installers using the Portals
    - `id` string, required — Format: <organization_id>:<slug>
    - `name` string, required — Human-friendly name for the role
    - `slug` string, required — URL-friendly name for the role
    - `type` 'portal_role', required — Type of the role
    - `expires_at` string, date-time — date and time then the role will expire
    - `organization_id` string, required — Id of an organization
    - `grants` Grant[], required — List of grants (permissions) applied to the role
      - `action` string, required
      - `resource` string
      - `effect` 'allow' | 'deny'
      - `conditions` GrantCondition[]
        - union
          - object — Check if attribute equals to any of the values
            - `attribute` string, required
            - `operation` 'equals', required
            - `values` string[], required
          - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition.
            - `attribute` string, required
            - `operation` 'not_equals', required
            - `values` string[], required
          - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'equals_current_user', required
          - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths.
            - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.
            - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute.
            - `operation` 'not_equals_current_user', required

## Changes

- **2026-08-27** `b29ea9adf72b` — 10 info
  - added the optional property `oneOf[#/components/schemas/OrgRole]/allOf[#/components/schemas/BaseRole]/grants/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCurrentUserCondition]/attributes` to the response with the `200` status
  - added the optional property `oneOf[#/components/schemas/PartnerRole]/allOf[#/components/schemas/BaseRole]/grants/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCurrentUserCondition]/attributes` to the response with the `200` status
  - added the optional property `oneOf[#/components/schemas/PortalRole]/allOf[#/components/schemas/BaseRole]/grants/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCurrentUserCondition]/attributes` to the response with the `200` status
  - added the optional property `oneOf[#/components/schemas/ShareRole]/allOf[#/components/schemas/BaseRole]/grants/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCurrentUserCondition]/attributes` to the response with the `200` status
  - …6 more

[Change history](https://skmtc.dev/epilot/apis/permissions-api/changes/v1/permissions/roles/:roleId/delete.md)

---

[API](https://skmtc.dev/epilot/apis/permissions-api.md) · [All operations](https://skmtc.dev/epilot/apis/permissions-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/epilot/permissions-api/revisions/b29ea9adf72b/schema)