openapi: 3.0.3
info:
  title: HashiCorp Vault KV Secrets Engine Auth Methods Secrets Data 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 Data
  description: Read, write, patch, and delete secret data versions in the KV v2 engine.
paths:
  /secret/data/{path}:
    get:
      operationId: readSecret
      summary: HashiCorp Vault Read Secret
      description: Retrieve the secret data and metadata for a given path from the KV v2 secrets engine. Returns the latest version by default or a specific version if the version parameter is specified.
      tags:
      - Secrets Data
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      - name: version
        in: query
        required: false
        description: Specifies the version to return. If not set the latest version is returned.
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: Successfully retrieved secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretDataResponse'
              examples:
                readSecret200Example:
                  summary: Default readSecret 200 response
                  x-microcks-default: true
                  value:
                    data:
                      data:
                        username: admin
                        password: s3cr3t
                      metadata:
                        created_time: '2025-03-15T14:30:00Z'
                        deletion_time: ''
                        destroyed: false
                        version: 1
        '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: writeSecret
      summary: HashiCorp Vault Write Secret
      description: Create or update a secret at the given path in the KV v2 secrets engine. Optionally supports check-and-set (CAS) operation to prevent accidental overwrites. Each write creates a new version.
      tags:
      - Secrets Data
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretDataRequest'
            examples:
              writeSecretRequestExample:
                summary: Default writeSecret request
                x-microcks-default: true
                value:
                  data:
                    username: admin
                    password: s3cr3t
      responses:
        '200':
          description: Secret written successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretWriteResponse'
              examples:
                writeSecret200Example:
                  summary: Default writeSecret 200 response
                  x-microcks-default: true
                  value:
                    data:
                      created_time: '2025-03-15T14:30:00Z'
                      deletion_time: ''
                      destroyed: false
                      version: 2
        '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: deleteLatestSecretVersion
      summary: HashiCorp Vault Delete Latest Secret Version
      description: Soft delete the latest version of a secret at the given path. The secret data is not permanently removed and can be undeleted. Use the destroy endpoint to permanently remove secret data.
      tags:
      - Secrets Data
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      responses:
        '204':
          description: Secret version soft deleted successfully
        '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
  /secret/delete/{path}:
    post:
      operationId: deleteSecretVersions
      summary: HashiCorp Vault Delete Secret Versions
      description: Soft delete one or more specified versions of a secret. The deleted versions can be recovered using the undelete endpoint. The key data is not permanently removed.
      tags:
      - Secrets Data
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionsRequest'
            examples:
              deleteSecretVersionsRequestExample:
                summary: Default deleteSecretVersions request
                x-microcks-default: true
                value:
                  versions:
                  - 1
                  - 2
      responses:
        '204':
          description: Secret versions soft deleted successfully
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secret/undelete/{path}:
    post:
      operationId: undeleteSecretVersions
      summary: HashiCorp Vault Undelete Secret Versions
      description: Restore one or more previously soft-deleted versions of a secret. Versions that have been permanently destroyed cannot be recovered.
      tags:
      - Secrets Data
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionsRequest'
            examples:
              undeleteSecretVersionsRequestExample:
                summary: Default undeleteSecretVersions request
                x-microcks-default: true
                value:
                  versions:
                  - 1
                  - 2
      responses:
        '204':
          description: Secret versions restored successfully
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secret/destroy/{path}:
    put:
      operationId: destroySecretVersions
      summary: HashiCorp Vault Destroy Secret Versions
      description: Permanently remove the data for one or more versions of a secret. Unlike soft delete, this operation is irreversible and the data cannot be recovered.
      tags:
      - Secrets Data
      parameters:
      - $ref: '#/components/parameters/SecretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionsRequest'
            examples:
              destroySecretVersionsRequestExample:
                summary: Default destroySecretVersions request
                x-microcks-default: true
                value:
                  versions:
                  - 1
                  - 2
      responses:
        '204':
          description: Secret versions permanently destroyed
        '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:
    SecretWriteResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SecretVersionMetadata'
    VersionsRequest:
      type: object
      required:
      - versions
      properties:
        versions:
          type: array
          items:
            type: integer
          description: List of version numbers to operate on.
          example:
          - 1
          - 2
          - 3
    VaultError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages.
          example:
          - permission denied
    SecretDataRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          description: Key-value pairs to store as the secret. Values can be strings, numbers, or nested objects.
          additionalProperties: true
        options:
          type: object
          properties:
            cas:
              type: integer
              description: Check-and-set value. If set, the write will only succeed if the current version matches this value. Set to 0 to write only if the key does not exist.
    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
    SecretDataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            data:
              type: object
              description: The secret key-value pairs.
              additionalProperties: true
            metadata:
              $ref: '#/components/schemas/SecretVersionMetadata'
  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