> ## Documentation Index > Fetch the complete documentation index at: https://docs.britive.com/llms.txt > Use this file to discover all available pages before exploring further. # Update / Move Secret > 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. ## OpenAPI ````json PATCH /api/v1/secretmanager/vault/{vaultId}/secrets { "openapi": "3.0.1", "info": { "title": "Secret Manager APIs", "version": "v1", "description": "API documentation for Secret Manager, Policy Administration, Notifications, Approval service, etc." }, "servers": [ { "url": "https://{tenantURL}", "description": "The primary server", "variables": { "tenantURL": { "default": "test.britive-app.com", "description": "The host of the server" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Approvals" }, { "name": "Notification Service" }, { "name": "Policy Administration" }, { "name": "Secrets Manager" }, { "name": "Secret Rotation" } ], "paths": { "/api/v1/secretmanager/vault/{vaultId}/secrets": { "patch": { "tags": [ "Secrets Manager" ], "summary": "Update / Move Secret", "description": "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.\n\n> **Note:** Only secrets (`entityType: secret`) can be moved. Folder nodes (`entityType: node`) cannot be moved using this endpoint.\n\n---\n\n### Update Field Values\nTo 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.\n\nFor **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\"`.\n\n**Versioning and rotation behaviour** is controlled by two optional query parameters:\n- `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`.\n- `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.\n\nFor **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.\n\n---\n\n### Rename\nTo 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.\n\n- The new name must be unique within the same parent folder.\n- 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.\"`\n\n---\n\n### Move (Secrets Only)\nTo 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.\n\nFor example, to move `my-secret` from `/folder1/subfolder1/my-secret` to `/folder1/my-secret`, send:\n```\nPATCH /vault/{vaultId}/secrets?path=/folder1/subfolder1/my-secret\n{ \"path\": \"/folder1/my-secret\" }\n```\n\n**Path format rules** — violation returns `400 \"Invalid secret path : {path}\"`:\n- Must start with `/`\n- Must not contain `//` (double slashes)\n- Must not end with `/` (trailing slash)\n- The basename (last path segment) must equal the existing secret name — renaming and moving in the same request is not supported\n\n**Required permissions on the destination folder** — violation returns `403 \"Move not allowed due to missing permissions : {folder}\"`:\n- `sm.node.create` — must be non-null and not Deny\n- `sm.node.delete` — must be non-null and not Deny\n\nThe destination parent folder must already exist in the vault; moving a secret to a non-existent folder is not supported.\n", "operationId": "updateSecretData", "parameters": [ { "name": "vaultId", "in": "path", "description": "vault Id", "required": "true", "schema": { "type": "string" }, "example": "a6ed82f6-32b5-46d8-a3a3-c36cc574abd9" }, { "name": "path", "in": "query", "description": "Current vault-relative path of the secret to update", "required": "true", "schema": { "type": "string" }, "example": "/machine/DB" }, { "name": "saveAsVersion", "in": "query", "description": "Archive the existing credential as a new version before applying the update", "required": "false", "schema": { "type": "boolean", "default": "false" }, "example": "true" }, { "name": "syncToTarget", "in": "query", "description": "Push the new credential to all mapped target accounts via the Broker", "required": "false", "schema": { "type": "boolean", "default": "false" }, "example": "false" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretDataDTO" }, "examples": { "updateFieldValues": { "summary": "Update secret field values (standard secret)", "value": { "value": { "url": "https://new-app.example.com", "username": "admin", "password": "new-p@ssw0rd" } } }, "updateDualAccountSecondaryValues": { "summary": "Update secondary credential values (dual-account secret only)", "value": { "secondaryValue": { "username": "secondary-admin", "password": "secondary-p@ssw0rd" } } }, "moveSecret": { "summary": "Move secret to a new folder", "value": { "path": "/new/destination/my-secret" } } } } }, "required": "false" }, "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request. Returned for the following violations:\n- `\"Not allowed to rename and move secret simultaneously.\"` — the request body changed both `name` and `path` at the same time.\n- `\"Invalid secret path : {path}\"` — the destination path is malformed (missing leading `/`, contains `//`, ends with `/`, or the basename does not match the existing secret name).\n- `\"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.\n- `\"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.\n- `SM-0178` — `rotationInterval` in hours is not a valid multiple of the vault's `dynamicRotationIntervalHours` (when `rotationIntervalUnit` is `HOURS`).\n- `SM-0179` — Hourly rotation is not allowed when the vault's `dynamicRotationIntervalHours` is `24`.\n- `SM-0180` — Hourly rotation interval is not allowed for static secrets.\n" }, "403": { "description": "Forbidden. Returned when the caller does not have the required permissions on the destination folder.\n- `\"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.\n" } } } } }, "components": { "schemas": { "SecretDataDTO": { "type": "object", "properties": { "entityType": { "pattern": "\\s*node\\s*|\\s*secret\\s*", "type": "string" }, "id": { "type": "string" }, "name": { "maxLength": "128", "minLength": "1", "pattern": "^[a-zA-Z0-9~`!@#$^&*\\\\(\\)_+=\\{\\}|;:\"?\\.>\\s-]{1,128}$", "type": "string" }, "value": { "type": "object", "additionalProperties": { "type": "string" } }, "secretMetadata": { "type": "object", "description": "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.\n", "additionalProperties": { "type": "string" } }, "description": { "maxLength": "255", "minLength": "0", "type": "string" }, "staticSecretTemplateId": { "type": "string" }, "secretMode": { "pattern": "shared|non-shared", "type": "string" }, "secretNature": { "pattern": "static|dynamic", "type": "string" }, "lastRotation": { "type": "string" }, "nextRotation": { "type": "string" }, "lastVerificationDate": { "type": "string", "description": "Timestamp of the most recent verification attempt (scheduled or manual), read-only." }, "lastVerificationStatus": { "type": "string", "description": "Outcome of the most recent verification attempt, read-only. Never `In Progress` — only stamped once a verification reaches a terminal state.", "enum": [ "Success", "Failed", "Timed Out" ] }, "path": { "type": "string", "description": "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.\n", "example": "/folder1/my-secret" }, "secretType": { "type": "string" }, "rotationInterval": { "type": "integer", "format": "int32" }, "status": { "type": "string", "enum": [ "Allow", "Deny", "Pending", "Timeout", "Rejected", "ApprovalRequired" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Allow", "Deny", "Pending", "Timeout", "Rejected", "ApprovalRequired" ] } }, "secondaryValue": { "type": "object", "description": "Secondary credential key-value map. Required only when dualAccount is true (Dual Account secrets).", "additionalProperties": { "type": "string" } }, "dualAccount": { "type": "boolean", "description": "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.\n", "default": "false" }, "rotationSettings": { "$ref": "#/components/schemas/RotationSettingsDTO" }, "filename": { "type": "string" }, "registrationStatus": { "type": "string" }, "delegationEnabled": { "type": "boolean" }, "rotationIntervalUnit": { "type": "string", "description": "Unit for the secret rotation interval. `DAYS` for static secrets, `HOURS` for dynamic secrets. Defaults to `DAYS` if not provided.\n", "enum": [ "DAYS", "HOURS" ], "default": "DAYS", "example": "DAYS" } } }, "RotationSettingsDTO": { "type": "object", "description": "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.\n", "properties": { "notificationMedium": { "type": "array", "description": "Notification medium IDs", "items": { "type": "string" } }, "recipients": { "$ref": "#/components/schemas/Recipients" }, "targetData": { "$ref": "#/components/schemas/RotationTargetDTO" } } }, "Recipients": { "type": "object", "properties": { "userIds": { "uniqueItems": "true", "type": "array", "items": { "type": "string" } }, "tags": { "uniqueItems": "true", "type": "array", "items": { "type": "string" } }, "approverGroups": { "uniqueItems": "true", "type": "array", "items": { "type": "string" } }, "channelIds": { "uniqueItems": "true", "type": "array", "items": { "type": "string" } }, "slackAppChannels": { "uniqueItems": "true", "type": "array", "items": { "type": "string" } }, "teamsAppChannels": { "type": "array", "items": { "$ref": "#/components/schemas/TeamsAppChannels" } } } }, "RotationTargetDTO": { "type": "object", "description": "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.\n", "required": [ "resource", "accountDetails" ], "properties": { "resource": { "type": "string", "description": "Identifier of the target resource. Must have rotation enabled in Resource Manager.", "example": "prod-linux-server" }, "accountDetails": { "$ref": "#/components/schemas/AccountDetailsDTO" }, "rotationTemplate": { "$ref": "#/components/schemas/RotationTemplateDTO", "description": "Optional. Selecting a rotation template is how a caller opts into rotation; omit it entirely to leave rotation unconfigured (e.g. for a secret that only wants verification).\n" }, "verificationEnabled": { "type": "boolean", "description": "Per-secret opt-in for secret verification (\"Allow Verifications\"). Requires targetData to be configured — cannot be true unless targetData is set.\n", "example": "false" }, "verificationTemplate": { "$ref": "#/components/schemas/VerificationTemplateDTO" } } }, "TeamsAppChannels": { "type": "object", "properties": { "team": { "type": "string" }, "channels": { "uniqueItems": "true", "type": "array", "items": { "type": "string" } } } }, "AccountDetailsDTO": { "type": "object", "description": "Account on the target resource that receives the updated credential", "properties": { "name": { "type": "string", "description": "Account name on the target resource", "example": "svc_account" }, "value": { "type": "string", "description": "Account identifier value", "example": "svc_account" } } }, "RotationTemplateDTO": { "type": "object", "description": "Defines the script/logic the Broker executes to update the credential on the target resource", "properties": { "templateId": { "type": "string", "description": "Unique identifier of the rotation template", "example": "linux-password-rotation" }, "templateName": { "type": "string", "description": "Human-readable name of the rotation template", "example": "Linux Password Rotation" }, "templateVariables": { "type": "array", "description": "Variables required by the rotation template. System-defined variables are populated automatically; user-defined variables must be supplied.\n", "items": { "$ref": "#/components/schemas/RotationTemplateVariableDTO" } } } }, "VerificationTemplateDTO": { "type": "object", "description": "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).\n", "properties": { "templateId": { "type": "string", "description": "Unique identifier of the verification template", "example": "linux-password-verification" }, "templateName": { "type": "string", "description": "Human-readable name of the verification template", "example": "Linux Password Verification" }, "templateVariables": { "type": "array", "description": "Variables required by the verification template. System-defined variables are populated automatically; user-defined variables must be supplied.\n", "items": { "$ref": "#/components/schemas/VerificationTemplateVariableDTO" } } } }, "RotationTemplateVariableDTO": { "type": "object", "description": "A single variable used by the rotation template", "properties": { "name": { "type": "string", "description": "Variable name as referenced in the rotation script", "example": "sudoUser" }, "isSystemDefined": { "type": "boolean", "description": "True if populated automatically by the system; false if user-supplied", "example": "false" }, "values": { "type": "array", "description": "One or more values for this variable", "items": { "type": "string" }, "example": [ "root" ] } } }, "VerificationTemplateVariableDTO": { "type": "object", "description": "A single variable used by the verification template", "properties": { "name": { "type": "string", "description": "Variable name as referenced in the verification script", "example": "sudoUser" }, "isSystemDefined": { "type": "boolean", "description": "True if populated automatically by the system; false if user-supplied", "example": "false" }, "values": { "type": "array", "description": "One or more values for this variable", "items": { "type": "string" }, "example": [ "root" ] } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } } ````