HashiCorp Vault Secrets Metadata API

openapi: 3.0.3
info:
  title: HashiCorp Vault KV Secrets Engine Auth Methods Secrets Metadata API
  description: 'The HashiCorp Vault KV (Key/Value) secrets engine API provides endpoints for reading, writing, versioning, and managing secrets stored in Vault. KV v2 supports secret versioning, metadata management, soft delete, and permanent destruction of secret versions. All paths are mounted under the KV engine mount point (default: secret/).'
  version: '2.0'
  contact:
    name: HashiCorp Support
    url: https://support.hashicorp.com
  termsOfService: https://www.hashicorp.com/terms-of-service
  license:
    name: BUSL-1.1
    url: https://github.com/hashicorp/vault/blob/main/LICENSE
  x-generated-from: documentation
servers:
- url: https://vault.example.com/v1
  description: Vault Server Instance
security:
- vaultToken: []
tags:
- name: Secrets Metadata
  description: Manage metadata and version history for KV v2 secrets.
paths:
  /secret/metadata/{path}:
    get:
      operationId: readSecretMetadata
      summary: HashiCorp Vault Read Secret Metadata
      description: Retrieve metadata and version history for a secret at the given path. Returns all version timestamps, current version number, max versions setting, CAS required status, and custom metadata.
      tags:
      - Secrets Metadata
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      responses:
        '200':
          description: Successfully retrieved secret metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretMetadataResponse'
              examples:
                readSecretMetadata200Example:
                  summary: Default readSecretMetadata 200 response
                  x-microcks-default: true
                  value:
                    data:
                      current_version: 2
                      max_versions: 10
                      oldest_version: 1
                      created_time: '2025-03-15T14:30:00Z'
                      updated_time: '2025-03-16T10:00:00Z'
                      versions:
                        '1':
                          created_time: '2025-03-15T14:30:00Z'
                          deletion_time: ''
                          destroyed: false
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
        '404':
          description: Secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: writeSecretMetadata
      summary: HashiCorp Vault Write Secret Metadata
      description: Create or update metadata for a secret including max versions, CAS required setting, delete version after duration, and custom metadata key-value pairs.
      tags:
      - Secrets Metadata
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretMetadataRequest'
            examples:
              writeSecretMetadataRequestExample:
                summary: Default writeSecretMetadata request
                x-microcks-default: true
                value:
                  max_versions: 10
                  cas_required: false
                  custom_metadata:
                    owner: platform-team
                    environment: production
      responses:
        '204':
          description: Metadata updated successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteSecretMetadata
      summary: HashiCorp Vault Delete Secret Metadata
      description: Permanently delete all metadata and versions for a secret at the given path. This operation is irreversible and removes all version history.
      tags:
      - Secrets Metadata
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      responses:
        '204':
          description: Metadata and all versions permanently deleted
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    SecretPath:
      name: path
      in: path
      required: true
      description: 'Path to the secret in the KV v2 store. Use forward slashes to organize secrets in a hierarchy. Example: myapp/production/db.'
      schema:
        type: string
        example: myapp/production/db
  schemas:
    SecretMetadataRequest:
      type: object
      properties:
        max_versions:
          type: integer
          minimum: 0
          description: Maximum number of versions to keep for this specific secret.
          example: 10
        cas_required:
          type: boolean
          description: When true, write operations require CAS parameter.
          example: false
        delete_version_after:
          type: string
          description: Duration after which versions are automatically soft-deleted.
          example: 0s
        custom_metadata:
          type: object
          description: User-provided key-value metadata stored alongside the secret.
          additionalProperties:
            type: string
          example:
            owner: platform-team
            environment: production
    VaultError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages.
          example:
          - permission denied
    SecretVersionMetadata:
      type: object
      properties:
        created_time:
          type: string
          format: date-time
          description: Time when this secret version was created.
          example: '2025-03-15T14:30:00Z'
        deletion_time:
          type: string
          description: Time when this version was or will be deleted. Empty string if not scheduled for deletion.
          example: ''
        destroyed:
          type: boolean
          description: Whether this version has been permanently destroyed.
          example: false
        version:
          type: integer
          description: The version number of this secret.
          example: 1
    SecretMetadataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            current_version:
              type: integer
              description: The current version number of the secret.
              example: 2
            max_versions:
              type: integer
              description: Maximum number of versions retained.
              example: 10
            oldest_version:
              type: integer
              description: The oldest version number available.
              example: 1
            created_time:
              type: string
              format: date-time
              description: Time when the secret was first created.
              example: '2025-03-15T14:30:00Z'
            updated_time:
              type: string
              format: date-time
              description: Time when the secret was last updated.
              example: '2025-03-16T10:00:00Z'
            cas_required:
              type: boolean
              example: false
            versions:
              type: object
              description: Map of version number to version metadata.
              additionalProperties:
                $ref: '#/components/schemas/SecretVersionMetadata'
            custom_metadata:
              type: object
              additionalProperties:
                type: string
  securitySchemes:
    vaultToken:
      type: apiKey
      in: header
      name: X-Vault-Token
      description: Vault token for authenticating API requests. Tokens can be created via login endpoints or the token auth method. The token must have appropriate policy permissions for the requested operations.
externalDocs:
  description: Vault KV v2 API Reference
  url: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2