Britive platform release 2026.09.02 is now live in production.

Create a node/secret

Prev Next
Post
/api/v1/secretmanager/vault/{vaultId}/secrets
Security
HTTP
Type bearer
Path parameters
vaultId
stringRequired

vault Id

Examplea6ed82f6-32b5-46d8-a3a3-c36cc574abd9
Query parameters
path
stringRequired

Secret/Node parent path

Example/machine/DB
Body parameters
Expand All
object
entityType
string
Pattern\s*node\s*|\s*secret\s*
id
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
200

successful operation

object
400

Bad request. Returned for the following rotation interval violations when rotationIntervalUnit is HOURS:

  • SM-0178 — rotationInterval in hours is not a valid multiple of the vault's dynamicRotationIntervalHours. Message: Secret rotation interval in hours must be a multiple of the vault's dynamic rotation interval ({n} hours). Valid options: {list}.
  • SM-0179 — Hourly rotation is not allowed when the vault's dynamicRotationIntervalHours is 24. Message: Hourly rotation interval is not allowed when the vault's dynamic rotation frequency is set to 24 hours. Please use a days-based rotation interval.
  • SM-0180 — Hourly rotation interval is not allowed for static secrets (secretNature: static). Message: Hourly rotation interval is not allowed for static secrets. Please use a days-based rotation interval.