---
title: "PATCH /v2/roles/{role_id}"
method: PATCH
path: "/v2/roles/{role_id}"
tags: ["roles"]
---

# PATCH /v2/roles/{role_id}

`PATCH /v2/roles/{role_id}`

Update a single Role

## Path parameters

- `role_id` string, required

## Headers

- `cloudzero-test-key` string

## Request body

- RoleUpdate
  - `name` string — Display name for the role
  - `description` string, nullable — Optional description of the role
  - `permission_set_ids` string[] — Set of permission set IDs assigned to this role
  - `data_access_filter` object, nullable — Data access filter configuration
    - `filter_type` 'NO_ACCESS' | 'LIMITED_ACCESS' | 'FULL_ACCESS'
    - `filter_dimensions` object — Dimension-based filter criteria with fixed values. Mutually exclusive with `dynamic_filter_dimensions`.
    - `dynamic_filter_dimensions` object, nullable — Dimension-based filter criteria whose values are resolved dynamically from the authenticated user's SSO claims at login, rather than being fixed when the role is created. Maps each dimension name to the SSO claim name (or list of claim names) whose values are applied as the filter for that dimension. Mutually exclusive with `filter_dimensions`.
    - `attribute_filters` object — Attribute-based filter criteria

## Response `200`

Successful Operation

- object
  - `role` Role
    - `id` string, required — Unique identifier for the role
    - `name` string, required — Display name for the role
    - `description` string, nullable — Optional description of the role
    - `permission_set_ids` string[], required — Set of permission set IDs assigned to this role
    - `data_access_filter` object, nullable — The data access filter associated with this role
      - `name` string
      - `description` string, nullable
      - `filter_type` string
      - `filter_dimensions` object — Dimension-based filter criteria with fixed values. Mutually exclusive with `dynamic_filter_dimensions`.
      - `dynamic_filter_dimensions` object, nullable — Dimension-based filter criteria whose values are resolved dynamically from the authenticated user's SSO claims at login, rather than being fixed when the role is created. Maps each dimension name to the SSO claim name (or list of claim names) whose values are applied as the filter for that dimension. Mutually exclusive with `filter_dimensions`.
      - `attribute_filters` object — Attribute-based filter criteria
    - `created_at` string, date-time — When the role was created
    - `created_by` string — API key ID that created the role
    - `last_updated_at` string, date-time — When the role was last updated
    - `last_updated_by` string — API key ID that last updated the role

## Other responses

- `400` — Bad Request Error
- `403` — Forbidden
- `404` — Not Found Error

---

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