---
title: "Update role"
method: POST
path: "/v2/permissions.updateRole"
tags: ["permissions"]
---

# Update role

`POST /v2/permissions.updateRole`

## Request

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

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

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

This endpoint does not change the role's permissions or keys. Use `permissions.setRolePermissions`, `keys.addRoles`, and `keys.removeRoles` for those.

**Important**: Keys keep the role after a rename. Requests that name the role, such as `keys.addRoles`, must use the new name. Key verification can return the old name for a short time while caches refresh. A name that another role 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/roles/<role_id>#write`

## Request body

- V2PermissionsUpdateRoleRequestBody
  - `role` string, required: The role to update. Pass the role ID (`role_...`) or its current name.
  - `name` string: New name for the role. The name must be unique in your workspace. Omit this field to keep the current name.
  - `description` string, nullable: New description for the role. Omit this field to keep the current description. Send null or an empty string to remove it.

## Response `200`

Role updated successfully

- V2PermissionsUpdateRoleResponseBody
  - `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` V2PermissionsUpdateRoleResponseData, required
    - `id` string, required: The ID of the updated role.
    - `name` string, required: The name of the role after the update.
    - `description` string: The description of the role after the update. Omitted when the role has no description.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - The root key or the workspace is disabled, or the key can read the role but lacks the required permission. A key that cannot read the role gets 404 instead.
- `404`: Not Found - The role 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 roles exist.
- `409`: Conflict - Another role in the workspace already uses this name
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

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

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/permissions.updateRole/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)