---
title: "Delete role"
method: POST
path: "/v2/permissions.deleteRole"
tags: ["permissions"]
---

# Delete role

`POST /v2/permissions.deleteRole`

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`

## Request body

- V2PermissionsDeleteRoleRequestBody
  - `role` string, 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

## Response `200`

Role deleted successfully

- V2PermissionsDeleteRoleResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` EmptyResponse, required — Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/4bd11a7252bc/schema)