UNunkeyed
permissions

Update role

Changed on

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
post/v2/permissions.updateRole

Request

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

Request body

rolestring required

The role to update. Pass the role ID (role_...) or its current name.

namestring

New name for the role. The name must be unique in your workspace. Omit this field to keep the current name.

descriptionstring nullable

New description for the role. Omit this field to keep the current description. Send null or an empty string to remove it.

Example request

{
  "role": "role_1234567890abcdef",
  "name": "support.readonly",
  "description": "Read-only access for customer support"
}

Response

Role updated successfully

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "role_1234567890abcdef",
    "name": "support.readonly",
    "description": "Read-only access for customer support"
  }
}

Changes