# (NEW!) Update Security Role

Partially update a security role. Only the fields present in the body are changed.

Business Rules:
- At least one of name, consentForm, or privileges must be present — a body with only expectedLastUpdatedEpoch, or an empty object, is rejected with 400.
- privileges, if supplied, fully replaces the existing set — it is not merged. An empty array clears all privileges. Omitting privileges never disturbs the stored role document.
- Renaming to the role's own current name (even differing only by case) is not a collision.

Optimistic Concurrency:
- expectedLastUpdatedEpoch is optional. If supplied and it doesn't match the role's current lastUpdatedEpoch, the write is rejected with 409 and code: STALE_UPDATE.

The response body is returned in the same shape as GET /security/roles/{id}.

The user submitting the request must have the Role Management privilege.

Endpoint: PATCH /security/roles/{id}
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `X-API-Key` (string, required)
    Customer-specific API key required to invoke API.

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

  - `Content-Type` (string, required)
    Enum: "application/json"

## Path parameters:

  - `id` (string, required)
    The unique ID of the role to update.
    Example: "6c15af83-d4a9-4772-875a-1c8a2bb1688f"

## Request fields (application/json):

  - `name` (string)
    New display name for the role. 1-32 characters after trimming. Renaming to the role's own current name (even differing only by case) is not a collision.
    Example: "Senior Compression Engineer"

  - `consentForm` (string)
    New consent text for the role.
    Example: "By accepting this role you agree to safeguard Pied Piper's proprietary middle-out compression algorithm, follow all platform security policies, and report suspected leaks immediately."

  - `privileges` (array)
    Full replacement set of privilege ids. An empty array clears all privileges. Omitting this field leaves the role's stored privileges untouched.
    Example: ["31bdde6b-1a2c-4d5e-8f90-1234567890ab"]

  - `expectedLastUpdatedEpoch` (integer)
    Optional optimistic-concurrency guard. If supplied and it doesn't match the role's current lastUpdatedEpoch, the write is rejected with 409 and code: STALE_UPDATE.
    Example: 1755600000000

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique ID of the role.
    Example: "6c15af83-d4a9-4772-875a-1c8a2bb1688f"

  - `name` (string, required)
    Display name of the role.
    Example: "Creative Producer"

  - `consentForm` (string)
    Consent text a user must accept to hold this role.
    Example: "By accepting this role you agree to uphold Pied Piper's brand and confidentiality guidelines when producing creative assets."

  - `privilegeCount` (integer)
    Number of privileges granted to the role.
    Example: 2

  - `privileges` (array)
    Flat array of permitted privilege ids only. Denied/unpermitted entries in the underlying role document are not surfaced.
    Example: ["31bdde6b-1a2c-4d5e-8f90-1234567890ab","9e187a4e-cfe4-419e-8c6c-2509e4bf400b"]

  - `userCount` (integer)
    Number of users currently assigned this role.
    Example: 12

  - `usedIn` (object)
    Everywhere the role is currently referenced.

  - `usedIn.presets` (array)
    Upload or filter presets whose role_ids include this role.

  - `usedIn.presets.id` (string)
    Example: "3a9f1c2e-8b4d-4f6a-9c1e-2b3a4c5d6e7f"

  - `usedIn.presets.name` (string)
    Example: "Pied Piper Marketing Upload"

  - `usedIn.presets.type` (string)
    Enum: "upload", "filter"

  - `createdBy` (string,null)
    User-profile id of the role's creator. null if the row has no recorded author.
    Example: "dc63db1b-1e63-43bc-877e-418931b6895c"

  - `createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1734000000000

  - `createdDate` (string,null)
    ISO 8601 creation date, derived from createdEpoch.
    Example: "2024-12-12T12:00:00.000Z"

  - `lastUpdatedBy` (string,null)
    User-profile id of the last user to update the role. null if the row has no recorded author.
    Example: "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec"

  - `lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1755600000000

  - `lastUpdatedDate` (string,null)
    ISO 8601 last-updated date, derived from lastUpdatedEpoch.
    Example: "2025-08-19T12:00:00.000Z"

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 404 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 409 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

  - `code` (string)
    Enum: "DUPLICATE_ROLE_NAME", "STALE_UPDATE"

  - `details` (object)
    Present only when code is DUPLICATE_ROLE_NAME.

  - `details.existingRoleId` (string)

## Response 422 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

  - `code` (string)
    Enum: "UNKNOWN_REFERENCES"

  - `details` (object)

  - `details.missingPrivilegeIds` (array)