---
title: "Update role information"
method: PUT
path: "/api/v1/roles/{role_name}"
tags: ["Roles"]
---

# Update role information

`PUT /api/v1/roles/{role_name}`

Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.

## Path parameters

- `role_name` string, required

## Request body

- V1rolesUpdateRole
  - `description` string — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.
  - `display_name` string — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.
  - `extends` string — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.
  - `permissions` string[] — List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role.

## Response `200`

Role updated successfully. Returns the modified role object with updated timestamps.

- RolesUpdateRoleResponse
  - `role` V1rolesRole
    - `default_creator` boolean — Indicates if this role is the default creator role for new organizations.
    - `default_member` boolean — Indicates if this role is the default member role for new users.
    - `dependent_roles_count` integer — Number of roles that extend from this role (dependent roles count). Read-only field.
    - `description` string — Detailed description of the role's purpose and capabilities. Maximum 2000 characters.
    - `display_name` string — Human-readable display name for the role. Used in user interfaces and reports.
    - `extends` string — Name of the base role that this role extends. Enables hierarchical role inheritance.
    - `id` string — Unique system-generated identifier for the role. Immutable once created.
    - `is_org_role` boolean — Indicates if this role is an organization role.
    - `name` string — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters.
    - `permissions` RolesRolePermission[] — List of permissions with role source information. Only included when 'include' parameter is specified in the request.
      - `create_time` string, date-time
      - `description` string
      - `id` string
      - `name` string
      - `role_name` string — Name of the role from which this permission was sourced
      - `update_time` string, date-time

---

[API](https://skmtc.net/scalekit/apis/scalekit-api-reference.md) · [All operations](https://skmtc.net/scalekit/apis/scalekit-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalekit/scalekit-api-reference/versions/a40d5d4650e5/schema)