Update / Move Secret

Patch

/api/v1/secretmanager/vault/{vaultId}/secrets

Updates a secret in the vault hierarchy. This endpoint handles three distinct operations — field-value update, rename, and move — determined by which fields are present in the request body. Only one operation should be performed per request.

Note: Only secrets (entityType: secret) can be moved. Folder nodes (entityType: node) cannot be moved using this endpoint.

Update Field Values

To update the credential data of a secret, include a value map in the request body containing the field names and their new values as defined by the secret's template.

For dual-account secrets, use secondaryValue instead of value to update the secondary credential fields. Attempting to update value (primary fields) on a dual-account secret is not allowed and returns 400 "Updating secret primary field values not allowed for dual account". Conversely, providing secondaryValue when dual account is not enabled on the secret returns 400 "Can not update secondary secret field values as dual account is not enabled".

Versioning and rotation behaviour is controlled by two optional query parameters:

saveAsVersion=true — snapshots the current credential values as a new immutable version before applying the update. This allows the previous credential to be retrieved later via the versions endpoint. Defaults to false.
syncToTarget=true — after saving, pushes the new credential to all mapped rotation target accounts via the Britive Broker. When syncToTarget is omitted or set to false, the target resources are not updated automatically and must be rotated separately.

For dual-account secrets, a successful syncToTarget sync triggers the Primary/Secondary account swap, alternating which account holds the active credential to ensure zero downtime during rotation.

Rename

To rename a secret, include the name field in the request body with the new name. The secret stays in its current folder; only its name changes.

The new name must be unique within the same parent folder.
Rename and move cannot be performed in the same request. If both name and path are changed simultaneously, the request is rejected with 400 "Not allowed to rename and move secret simultaneously."

Move (Secrets Only)

To move a secret to a different folder, include the path field in the request body with the full destination vault-relative path including the secret name. The path query parameter identifies the secret's current location; the path body field specifies where it should be moved to.

For example, to move my-secret from /folder1/subfolder1/my-secret to /folder1/my-secret, send:

PATCH /vault/{vaultId}/secrets?path=/folder1/subfolder1/my-secret
{ "path": "/folder1/my-secret" }

Path format rules — violation returns 400 "Invalid secret path : {path}":

Must start with /
Must not contain // (double slashes)
Must not end with / (trailing slash)
The basename (last path segment) must equal the existing secret name — renaming and moving in the same request is not supported

Required permissions on the destination folder — violation returns 403 "Move not allowed due to missing permissions : {folder}":

sm.node.create — must be non-null and not Deny
sm.node.delete — must be non-null and not Deny

The destination parent folder must already exist in the vault; moving a secret to a non-existent folder is not supported.

Security

HTTP

Type bearer

Path parameters

vaultId

stringRequired

vault Id

Examplea6ed82f6-32b5-46d8-a3a3-c36cc574abd9

Query parameters

path

stringRequired

Current vault-relative path of the secret to update

Example/machine/DB

saveAsVersion

boolean

Archive the existing credential as a new version before applying the update

Defaultfalse

Exampletrue

syncToTarget

boolean

Push the new credential to all mapped target accounts via the Broker

Defaultfalse

Examplefalse

Body parameters

updateFieldValues

Update secret field values (standard secret)

{
  "value": {
    "url": "https://new-app.example.com",
    "username": "admin",
    "password": "new-p@ssw0rd"
  }
}

Expand All

object

entityType

string

Pattern\s*node\s*|\s*secret\s*

string

name

string

Min length1

Max length128

Pattern^[a-zA-Z0-9~`!@#$^&*\_+=\{\}|;:"?\.>\s-]{1,128}$

value

object

property*

string additionalProperties

secretMetadata

object

Read-only map of metadata field names to their plain-text values. Populated automatically from fields whose metadata flag is true in the static secret template. Changes to metadata fields do not trigger a new secret version.

property*

string additionalProperties

description

string

Min length0

Max length255

staticSecretTemplateId

string

secretMode

string

Patternshared|non-shared

secretNature

string

Patternstatic|dynamic

lastRotation

string

nextRotation

string

lastVerificationDate

string

Timestamp of the most recent verification attempt (scheduled or manual), read-only.

lastVerificationStatus

string

Outcome of the most recent verification attempt, read-only. Never In Progress — only stamped once a verification reaches a terminal state.

Valid values[ "Success", "Failed", "Timed Out" ]

path

string

Vault-relative path of the secret. When included in a PATCH request body with a value that differs from the current path, triggers a move operation. Only secrets (entityType=secret) can be moved; folder nodes cannot. Must start with '/', must not contain '//', must not end with '/', and the basename must match the existing secret name (rename and move are mutually exclusive). The destination folder must exist and the caller must have sm.node.create and sm.node.delete permissions on it.

Example/folder1/my-secret

secretType

string

rotationInterval

integer (int32)

status

string

Valid values[ "Allow", "Deny", "Pending", "Timeout", "Rejected", "ApprovalRequired" ]

metadata

object

property*

string additionalProperties

Valid values[ "Allow", "Deny", "Pending", "Timeout", "Rejected", "ApprovalRequired" ]

secondaryValue

object

Secondary credential key-value map. Required only when dualAccount is true (Dual Account secrets).

property*

string additionalProperties

dualAccount

boolean

When true the secret holds two sets of credentials (Primary in value and Secondary in secondaryValue) that alternate on each rotation cycle to ensure zero downtime.

Defaultfalse

rotationSettings

object (RotationSettingsDTO)

Rotation target, notification, and secret verification settings embedded in a secret. Secret verification is decoupled from rotation but reuses targetData to identify the resource to check.

notificationMedium

Array of string

Notification medium IDs

string

recipients

object (Recipients)

userIds

Array of string

string

tags

Array of string

string

approverGroups

Array of string

string

channelIds

Array of string

string

slackAppChannels

Array of string

string

teamsAppChannels

Array of object (TeamsAppChannels)

object

team

string

channels

Array of string

string

targetData

object (RotationTargetDTO)

The target resource and account a secret checks/rotates against, along with the optional rotation template the Broker executes. resource/accountDetails are required whenever targetData is supplied at all -- both rotation and secret verification (see verificationEnabled/verificationTemplate below) rely on them. rotationTemplate is required only to opt into rotation itself; a secret may supply targetData with verificationEnabled/verificationTemplate set and no rotationTemplate, in which case rotation simply stays unconfigured for that secret.

resource

string Required

Identifier of the target resource. Must have rotation enabled in Resource Manager.

Exampleprod-linux-server

accountDetails

object (AccountDetailsDTO) Required

Account on the target resource that receives the updated credential

name

string

Account name on the target resource

Examplesvc_account

value

string

Account identifier value

Examplesvc_account

rotationTemplate

object (RotationTemplateDTO)

Defines the script/logic the Broker executes to update the credential on the target resource

templateId

string

Unique identifier of the rotation template

Examplelinux-password-rotation

templateName

string

Human-readable name of the rotation template

ExampleLinux Password Rotation

templateVariables

Array of object (RotationTemplateVariableDTO)

Variables required by the rotation template. System-defined variables are populated automatically; user-defined variables must be supplied.

object

A single variable used by the rotation template

name

string

Variable name as referenced in the rotation script

ExamplesudoUser

isSystemDefined

boolean

True if populated automatically by the system; false if user-supplied

Examplefalse

values

Array of string

One or more values for this variable

Example[ "root" ]

string

verificationEnabled

boolean

Per-secret opt-in for secret verification ("Allow Verifications"). Requires targetData to be configured — cannot be true unless targetData is set.

Examplefalse

verificationTemplate

object (VerificationTemplateDTO)

The resource type's verification template (and per-secret variable values) this secret should be checked against. A resource type may have multiple verification templates, so templateId selects which one applies to this secret. Required — and validated for completeness (templateId, and at least one fully-populated templateVariable) — only when verificationEnabled is true; otherwise optional, and accepted as-is with no completeness checks (e.g. a caller may leave a previously-selected template in place while toggling verification off).

templateId

string

Unique identifier of the verification template

Examplelinux-password-verification

templateName

string

Human-readable name of the verification template

ExampleLinux Password Verification

templateVariables

Array of object (VerificationTemplateVariableDTO)

Variables required by the verification template. System-defined variables are populated automatically; user-defined variables must be supplied.

object

A single variable used by the verification template

name

string

Variable name as referenced in the verification script

ExamplesudoUser

isSystemDefined

boolean

True if populated automatically by the system; false if user-supplied

Examplefalse

values

Array of string

One or more values for this variable

Example[ "root" ]

string

filename

string

registrationStatus

string

delegationEnabled

boolean

rotationIntervalUnit

string

Unit for the secret rotation interval. DAYS for static secrets, HOURS for dynamic secrets. Defaults to DAYS if not provided.

Valid values[ "DAYS", "HOURS" ]

Default"DAYS"

ExampleDAYS

Responses

204

No content

400

Bad request. Returned for the following violations:

"Not allowed to rename and move secret simultaneously." — the request body changed both name and path at the same time.
"Invalid secret path : {path}" — the destination path is malformed (missing leading /, contains //, ends with /, or the basename does not match the existing secret name).
"Updating secret primary field values not allowed for dual account" — value was provided in the request body for a dual-account secret; use secondaryValue instead.
"Can not update secondary secret field values as dual account is not enabled" — secondaryValue was provided but the secret does not have dual account enabled.
SM-0178 — rotationInterval in hours is not a valid multiple of the vault's dynamicRotationIntervalHours (when rotationIntervalUnit is HOURS).
SM-0179 — Hourly rotation is not allowed when the vault's dynamicRotationIntervalHours is 24.
SM-0180 — Hourly rotation interval is not allowed for static secrets.

403

Forbidden. Returned when the caller does not have the required permissions on the destination folder.

"Move not allowed due to missing permissions : {folder}" — the caller is missing sm.node.create or sm.node.delete (or both) on the destination folder.

Was this article helpful?