openapi: 3.0.3
info:
  title: HashiCorp Vault KV Secrets Engine Auth Methods Secrets Engines 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 Engines
  description: Mount, unmount, list, and configure secrets engines.
paths:
  /sys/mounts:
    get:
      operationId: listSecretsMounts
      summary: HashiCorp Vault List Secrets Engine Mounts
      description: List all mounted secrets engines with their configuration, accessor, and options. Returns a map of mount path to engine configuration.
      tags:
      - Secrets Engines
      responses:
        '200':
          description: Successfully retrieved secrets engine mounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MountsResponse'
              examples:
                listSecretsMounts200Example:
                  summary: Default listSecretsMounts 200 response
                  x-microcks-default: true
                  value:
                    data:
                      secret/:
                        type: kv
                        description: Key-Value store
                        options:
                          version: '2'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sys/mounts/{path}:
    post:
      operationId: enableSecretsEngine
      summary: HashiCorp Vault Enable Secrets Engine
      description: Mount a new secrets engine at the specified path. Supported types include aws, azure, consul, database, gcp, kv, nomad, pki, rabbitmq, ssh, totp, transit, and more.
      tags:
      - Secrets Engines
      parameters:
      - $ref: '#/components/parameters/MountPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnableMountRequest'
            examples:
              enableSecretsEngineRequestExample:
                summary: Default enableSecretsEngine request
                x-microcks-default: true
                value:
                  type: kv
                  description: Application secrets
                  options:
                    version: '2'
      responses:
        '204':
          description: Secrets engine enabled 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: disableSecretsEngine
      summary: HashiCorp Vault Disable Secrets Engine
      description: Unmount a secrets engine. All secrets stored in this engine will be revoked. This operation is irreversible.
      tags:
      - Secrets Engines
      parameters:
      - $ref: '#/components/parameters/MountPath'
      responses:
        '204':
          description: Secrets engine unmounted successfully
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    MountsResponse:
      type: object
      properties:
        data:
          type: object
          description: Map of mount path to secrets engine configuration.
          additionalProperties:
            $ref: '#/components/schemas/MountConfig'
    VaultError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages.
          example:
          - permission denied
    EnableMountRequest:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: Type of secrets engine to mount.
          example: kv
        description:
          type: string
          description: Human-friendly description.
          example: Application secrets
        options:
          type: object
          additionalProperties:
            type: string
    MountConfig:
      type: object
      properties:
        type:
          type: string
          description: Secrets engine type.
          example: kv
        description:
          type: string
          description: Description of the mount.
          example: Key-Value store
        accessor:
          type: string
          description: Mount accessor.
          example: kv_abc123
        options:
          type: object
          additionalProperties:
            type: string
  parameters:
    MountPath:
      name: path
      in: path
      required: true
      description: Mount path for the auth method or secrets engine. Must not contain slashes at the beginning or end.
      schema:
        type: string
        example: approle
  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