---
title: "Update permission"
method: POST
path: "/v2/permissions.updatePermission"
tags: ["permissions"]
---

# Update permission

`POST /v2/permissions.updatePermission`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/permissions.updatePermission`
- Auth: HTTP bearer

Update the name, slug, or description of a permission, identified by its ID or slug.

Omitted fields keep their current values. A request with no fields to update returns the stored permission without a write.

**Important**: Keys and roles reference the permission by ID, so they keep the permission after a slug change. Key verification can return the old slug for a short time while caches refresh. A slug that another permission in your workspace already uses returns 409.

**Required Permissions**

Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#write`

## Request body

- V2PermissionsUpdatePermissionRequestBody
  - `permission` string, required: The permission to update. Pass the permission ID (`perm_...`) or its current slug.
  - `name` string: New human-readable name for the permission. Omit this field to keep the current name.
  - `slug` string: New slug for the permission. Keys and roles that have this permission get the new slug in verification responses. The slug must be unique in your workspace. Omit this field to keep the current slug.
  - `description` string, nullable: New description for the permission. Omit this field to keep the current description. Send null or an empty string to remove it.

## Response `200`

Permission updated successfully

- V2PermissionsUpdatePermissionResponseBody
  - `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` Permission, required
    - `id` string, required: The unique identifier for this permission within Unkey's system. Generated automatically when the permission is created and used to reference this permission in API operations. Always begins with 'perm_' followed by alphanumeric characters and underscores.
    - `name` string, required: The human-readable name for this permission that describes its purpose. Should be descriptive enough for developers to understand what access it grants. Use clear, semantic names that reflect the resources or actions being permitted.
    - `slug` string, required: The unique URL-safe identifier for this permission.
    - `description` string: Optional detailed explanation of what this permission grants access to. Helps team members understand the scope and implications of granting this permission. Include information about what resources can be accessed and what actions can be performed. Not visible to end users - this is for internal documentation and team clarity.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - The root key or the workspace is disabled, or the key can read the permission but lacks the required permission. A key that cannot read the permission gets 404 instead.
- `404`: Not Found - The permission does not exist in your workspace, or your root key cannot read it. Both cases return the same response, so a root key cannot learn which permissions exist.
- `409`: Conflict - Another permission in the workspace already uses this slug
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-09** `ce8c250ad906`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/permissions.updatePermission/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.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)