---
title: "Delete permission"
method: POST
path: "/v2/permissions.deletePermission"
tags: ["permissions"]
---

# Delete permission

`POST /v2/permissions.deletePermission`

Remove a permission from your workspace. This also removes the permission from all API keys and roles.

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

**Required Permissions**

Your root key must have the following permission:
- `rbac.*.delete_permission`

## Request body

- V2PermissionsDeletePermissionRequestBody
  - `permission` string, required — Specifies which permission to permanently delete from your workspace. This can be a permission ID or a permission slug. WARNING: Deleting a permission has immediate and irreversible consequences: - All API keys with this permission will lose that access immediately - All roles containing this permission will have it removed - Any verification requests checking for this permission will fail - This action cannot be undone Before deletion, ensure you: - Have updated any keys or roles that depend on this permission - Have migrated to alternative permissions if needed - Have notified affected users about the access changes

## Response `200`

Permission deleted successfully

- V2PermissionsDeletePermissionResponseBody
  - `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
- `404` — Not Found - The specified permission does not exist
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-08-11** `59efaed65ec4` — 1 breaking, 1 warning, 1 info
  - the `permission` request property's maxLength was decreased to `128`
  - changed the pattern of the request property `permission` from `^[a-zA-Z][a-zA-Z0-9._-]*$` to `^[a-zA-Z0-9_:\-\.\*]+$`
  - the `permission` request property's minLength was decreased from `3` to `1`
- **2026-07-14** `43ad1ce9a152` — 2 info
  - the endpoint scheme security `bearer` was added to the API
  - the endpoint scheme security `rootKey` was removed from the API
- **2026-02-27** `551df53dd45d` — 1 info
  - added the non-success response with the status `429`
- **2026-01-14** `9a9c22b6dd09` — 1 info
  - api operation id `deletePermission` removed and replaced with `permissions.deletePermission`

[Change history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/permissions.deletePermission/post.md)

---

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