---
title: "Fully replace a permission's fields"
method: PUT
path: "/permissions/{id}"
tags: ["Permission"]
---

# Fully replace a permission's fields

`PUT /permissions/{id}`

Performs a full replacement of the permission identified by {id}. Resource and action are required on every call, and description is fully replaced by the value supplied in the request body -- omitting description clears it. This is a full-replace operation, not a partial patch; use it only when you intend to set every field explicitly, since there is no separate partial-update endpoint for permissions.

Preconditions: the caller must be authenticated and hold the UPDATE_PERMISSION permission for the tenant, and the permission identified by {id} must already exist (create it first with POST /permissions).

On success, returns the updated permission; createdAt and updatedAt are always null in the current implementation. Returns 404 when {id} does not exist.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Request body

- PermissionUpdateRequest — Request body for updating a permission
  - `resource` string, required — Name of the resource this permission will govern (e.g., 'user', 'roster'). At most 100 characters. Required on every call: PUT /permissions/{id} is a full replace, so this value must always be supplied.
  - `action` string, required — Name of the action this permission will grant on the resource (e.g., 'read', 'create'). At most 100 characters. Required on every call: PUT /permissions/{id} is a full replace, so this value must always be supplied.
  - `description` string — Human-readable explanation of what the permission allows. At most 500 characters. Optional: since PUT /permissions/{id} is a full replace, omitting this value clears any existing description.

## Response `200`

The permission after the full replacement, reflecting the resource, action, and description values supplied in the request body. Note: createdAt and updatedAt are always null in the current implementation.

- PermissionResponseDto — Permission information response
  - `id` string — Server-assigned unique identifier for the permission.
  - `resource` string — Name of the resource this permission governs (e.g. 'user', 'roster'). Mirrors the resource value supplied when the permission was created or last replaced.
  - `action` string — Name of the action this permission grants on the resource (e.g. 'read', 'create'). Mirrors the action value supplied when the permission was created or last replaced.
  - `description` string — Human-readable explanation of what the permission allows. Optional; may be null if it was not supplied at creation.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400` — Returned when the downstream data service rejects the request body as invalid (for example, a missing resource or action). This endpoint performs no local bean-validation, so the exact trigger is determined by the permissions data service.
- `404` — No permission with the given id exists in this tenant's catalog. Create it first with POST /permissions, or verify the id and tenant-id header.
- `500` — An unexpected error occurred while replacing the permission, typically a downstream data-service failure. Retry the request or contact support if the error persists.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)