PATCH api/v1/folder/{id} — Assigning a Secret Policy via the API

The PATCH /api/v1/folder/{id} endpoint allows an API account to update folder properties, including assigning a Secret Policy. This page documents the exact permissions required and the error responses you may receive when assigning a policy that includes an Enforced Privileged Account.

Required Role Permissions

To call PATCH /api/v1/folder/{id} and assign a Secret Policy, the API account's role must include all of the following permissions:

Assign Secret Policy — required to associate a policy with a folder.
View Secret Policy — required to read the policy definition.
Edit Folder (or Owner permission on the target folder) — required to modify the folder record.

Additional Requirement: Policies with an Enforced Privileged Account

A Secret Policy may include a Privileged Account setting (configured on the Remote Password Changing tab of the policy). When the policy's Default only checkbox is unchecked (that is, the policy applies the Privileged Account as Enforced), the API caller is also required to have:

Role permission: Allow List Secret Access for Assigning Policy — grants the right to assign a policy to a folder or secret when the caller has only List access (rather than full View access) to the Privileged Account secret referenced by the policy.
Secret ACL: List on the Privileged Account secret referenced by the policy — the caller must have at least List permission on that specific secret.

The broader View Secret role permission is not required for this operation. Only the secret-level List ACL on the Privileged Account secret is needed.

There are security implications to granting Allow List Secret Access for Assigning Policy. An API account with this permission and List access to a Privileged Account secret can create secrets that inherit the Privileged Account's reset capabilities, effectively gaining indirect access to that account. Grant this permission only to trusted service accounts.

When the Default Only Checkbox Is Checked

If the policy's Privileged Account setting has Default only checked (PolicyApplyCode = Default), the per-secret access check on the Privileged Account is not performed. In that case, the additional role permission and secret-level ACL described above are not required.

Response Codes

HTTP Status	Code	Cause
200 OK	—	Policy assigned successfully.
400 Bad Request	—	Invalid request body or folder ID.
403 Forbidden	AccessDenied	The caller is missing the required role permission or secret-level ACL. The response body names the specific missing permission and ACL, for example: `AccessDenied: The caller requires the 'AllowListSecretAccessForAssigningPolicy' role permission and List access on secret '{secret name}' to assign this policy.` This response is returned when the policy being assigned has an Enforced Privileged Account and the caller lacks Allow List Secret Access for Assigning Policy or the List ACL on the referenced secret.
403 Forbidden	AccessDenied	The caller does not have Edit or Owner permission on the target folder, or lacks Assign Secret Policy / View Secret Policy role permissions.
404 Not Found	—	The specified folder ID does not exist or is not visible to the caller.

Prior to this fix, the missing-permission scenario for an Enforced Privileged Account returned HTTP 500. It now returns HTTP 403 with a descriptive error message.

Minimum Least-Privilege Role for an API Account

Use the following checklist when configuring a least-privilege API account that must assign Secret Policies to folders via the REST API: