openapi: 3.1.0
info:
  title: HashiCorp Vault HTTP Auth - AppRole Secrets - KV v2 API
  description: The Vault HTTP API provides full access to Vault functionality via HTTP. Every aspect of Vault can be controlled via this API including secrets management, authentication, system configuration, identity, and policy management.
  version: 1.15.0
  contact:
    name: HashiCorp
    url: https://www.vaultproject.io/
  license:
    name: Business Source License 1.1
    url: https://github.com/hashicorp/vault/blob/main/LICENSE
servers:
- url: https://127.0.0.1:8200/v1
  description: Local Vault server
- url: https://{vault_host}:{port}/v1
  description: Custom Vault server
  variables:
    vault_host:
      default: 127.0.0.1
    port:
      default: '8200'
security:
- VaultToken: []
tags:
- name: Secrets - KV v2
  description: Key/Value secrets engine version 2
paths:
  /secret/data/{path}:
    get:
      operationId: readKVSecret
      summary: Read KV secret (v2)
      description: Reads a secret from the KV v2 secrets engine at the given path.
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: query
        schema:
          type: integer
        description: Specific version to read
      responses:
        '200':
          description: Secret data
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  lease_id:
                    type: string
                  renewable:
                    type: boolean
                  lease_duration:
                    type: integer
                  data:
                    type: object
                    properties:
                      data:
                        type: object
                        additionalProperties: true
                      metadata:
                        type: object
                        properties:
                          created_time:
                            type: string
                            format: date-time
                          custom_metadata:
                            type: object
                          deletion_time:
                            type: string
                          destroyed:
                            type: boolean
                          version:
                            type: integer
        '404':
          description: Secret not found
    post:
      operationId: createKVSecret
      summary: Create or update KV secret (v2)
      description: Creates a new version of a secret at the specified path.
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                options:
                  type: object
                  properties:
                    cas:
                      type: integer
                      description: Check-And-Set version for optimistic locking
                data:
                  type: object
                  additionalProperties: true
                  description: Secret key-value pairs
      responses:
        '200':
          description: Secret created/updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      created_time:
                        type: string
                        format: date-time
                      deletion_time:
                        type: string
                      destroyed:
                        type: boolean
                      version:
                        type: integer
    delete:
      operationId: deleteKVSecretLatest
      summary: Delete latest version of KV secret
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Secret version deleted (soft delete)
  /secret/metadata/{path}:
    get:
      operationId: getKVMetadata
      summary: Read KV secret metadata
      description: Returns metadata and version history for the secret at the given path.
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Secret metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      cas_required:
                        type: boolean
                      created_time:
                        type: string
                        format: date-time
                      current_version:
                        type: integer
                      delete_version_after:
                        type: string
                      max_versions:
                        type: integer
                      oldest_version:
                        type: integer
                      updated_time:
                        type: string
                        format: date-time
                      custom_metadata:
                        type: object
                      versions:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            created_time:
                              type: string
                              format: date-time
                            deletion_time:
                              type: string
                            destroyed:
                              type: boolean
    delete:
      operationId: deleteKVMetadata
      summary: Delete all versions and metadata
      description: Permanently deletes the key metadata and all version data.
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: All versions and metadata deleted
  /secret/delete/{path}:
    post:
      operationId: deleteKVSecretVersions
      summary: Delete specific versions of KV secret
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - versions
              properties:
                versions:
                  type: array
                  items:
                    type: integer
      responses:
        '204':
          description: Versions deleted (soft delete)
  /secret/undelete/{path}:
    post:
      operationId: undeleteKVSecretVersions
      summary: Undelete versions of KV secret
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - versions
              properties:
                versions:
                  type: array
                  items:
                    type: integer
      responses:
        '204':
          description: Versions restored
  /secret/destroy/{path}:
    post:
      operationId: destroyKVSecretVersions
      summary: Permanently destroy versions
      description: Permanently removes the data for the specified versions (cannot be recovered).
      tags:
      - Secrets - KV v2
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - versions
              properties:
                versions:
                  type: array
                  items:
                    type: integer
      responses:
        '204':
          description: Versions permanently destroyed
components:
  securitySchemes:
    VaultToken:
      type: apiKey
      name: X-Vault-Token
      in: header
      description: Vault client token