> ## 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.

# Create a node/secret

## OpenAPI

````json POST /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": {
      "post": {
        "tags": [
          "Secrets Manager"
        ],
        "summary": "Create a node/secret",
        "operationId": "createSecretData",
        "parameters": [
          {
            "name": "vaultId",
            "in": "path",
            "description": "vault Id",
            "required": "true",
            "schema": {
              "type": "string"
            },
            "example": "a6ed82f6-32b5-46d8-a3a3-c36cc574abd9"
          },
          {
            "name": "path",
            "in": "query",
            "description": "Secret/Node parent path",
            "required": "true",
            "schema": {
              "type": "string"
            },
            "example": "/machine/DB"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SecretDataDTO"
              }
            }
          },
          "required": "false"
        },
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned for the following rotation interval violations when `rotationIntervalUnit` is `HOURS`:\n- `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}.`\n- `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.`\n- `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.`\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"
      }
    }
  }
}
````