---
title: "Update role"
method: PATCH
path: "/zones/{zoneId}/roles/{roleId}"
tags: ["Zone Roles"]
---

# Update role

`PATCH /zones/{zoneId}/roles/{roleId}`

## Request

- Base URL: `https://docs.keycard.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.keycard.ai/zones/{zoneId}/roles/{roleId}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `/service-account-token`

Updates a customer-owned role's description. The identifier is immutable, and platform-owned roles cannot be modified.

## Path parameters

- `zoneId` string, required
- `roleId` string, required

## Request body

- IamRoleUpdate: Schema for updating an existing role. The role identifier is immutable.
  - `description` string, nullable: Human-readable description (set to null to unset)

## Response `200`

A role that can be assigned to users within a zone.

- IamRole: A role that can be assigned to users within a zone.
  - `id` string, required: Unique identifier of the role
  - `zone_id` string, required: Zone this role belongs to
  - `identifier` string, required: Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.
  - `description` string, nullable: Human-readable description
  - `owner_type` 'platform' | 'customer', required: Who owns this role. Platform-owned roles are managed by Keycard and cannot be modified or deleted via the API; customer-owned roles are user-created.
  - `created_at` string, date-time, required: Entity creation timestamp
  - `updated_at` string, date-time, required: Entity update timestamp

## Other responses

- `403`: Error response
- `404`: Error response
- `default`: Error response

## Changes

- **2026-08-26** `d65d51379d93`: 3 info
  - added the non-success response with the status `403`
  - added the non-success response with the status `404`
  - the `identifier` response's property pattern `^[a-z0-9]+(?:[-_][a-z0-9]+)*$` was added for the status `200`
- **2026-06-09** `7e0e4fa2e16f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/:zoneId/roles/:roleId/patch.md)

---

[API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)