UNunkeyed
permissions

Delete role

Changed on

Remove a role from your workspace. This also removes the role from all assigned API keys.

Important: This operation cannot be undone and immediately affects all API keys that had this role assigned.

Required Permissions

Your root key must have the following permission:

  • rbac.*.delete_role
post/v2/permissions.deleteRole

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/permissions.deleteRole
  • Auth
    HTTP bearer

Request body

rolestring required

Unique identifier of the role to permanently delete from your workspace. Must either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.

WARNING: Deletion is immediate and irreversible with significant consequences:

  • All API keys assigned this role will lose the associated permissions
  • Access to resources protected by this role's permissions will be denied
  • Any authorization logic depending on this role will start failing
  • Historical analytics referencing this role remain intact

Before deletion, ensure:

  • You've updated any dependent authorization logic or code
  • You've migrated any keys to use alternative roles or direct permissions
  • You've notified relevant team members of the access changes

Example request

{
  "role": "role_dns_manager"
}

Response

Role deleted successfully

dataEmptyResponse required

Empty response object by design. A successful response indicates this operation was successfully executed.

Example response

{
  "meta": {
    "requestId": "req_123"
  }
}

Changes

  • 6ed4b9847395Revision changes
    • info

      added the non-success response with the status

  • 4bd11a7252bcRevision changes
    • breaking

      the request property's maxLength was decreased to 128

    • info

      the request property's minLength was decreased from 3 to 1

    • info

      removed the pattern ^[a-zA-Z0-9_:\-\.\*]+$ from the request property