HashiCorp Vault Secrets Config API

openapi: 3.0.3
info:
  title: HashiCorp Vault KV Secrets Engine Auth Methods Secrets Config 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 Config
  description: Configure KV v2 engine settings such as max versions and CAS required.
paths:
  /secret/config:
    get:
      operationId: getKvConfig
      summary: HashiCorp Vault Get KV Configuration
      description: Retrieve the current configuration for the KV v2 secrets engine including maximum number of versions, CAS required setting, delete version after duration, and whether the engine is enabled.
      tags:
      - Secrets Config
      responses:
        '200':
          description: Successfully retrieved KV engine configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KvConfigResponse'
              examples:
                getKvConfig200Example:
                  summary: Default getKvConfig 200 response
                  x-microcks-default: true
                  value:
                    data:
                      max_versions: 10
                      cas_required: false
                      delete_version_after: 0s
        '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
    post:
      operationId: setKvConfig
      summary: HashiCorp Vault Set KV Configuration
      description: Configure backend-level settings for the KV v2 secrets engine including maximum number of secret versions to keep and whether CAS (check-and-set) is required for write operations.
      tags:
      - Secrets Config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KvConfigRequest'
            examples:
              setKvConfigRequestExample:
                summary: Default setKvConfig request
                x-microcks-default: true
                value:
                  max_versions: 10
                  cas_required: false
      responses:
        '204':
          description: Configuration 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
components:
  schemas:
    VaultError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: List of error messages.
          example:
          - permission denied
    KvConfigResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            max_versions:
              type: integer
              example: 10
            cas_required:
              type: boolean
              example: false
            delete_version_after:
              type: string
              example: 0s
    KvConfigRequest:
      type: object
      properties:
        max_versions:
          type: integer
          minimum: 0
          description: Maximum number of versions to keep per secret. Older versions are automatically deleted when this limit is exceeded. Set to 0 for unlimited versions.
          example: 10
        cas_required:
          type: boolean
          description: When true, all write operations require check-and-set (CAS) parameter to prevent accidental overwrites.
          example: false
        delete_version_after:
          type: string
          description: Duration after which a secret version is automatically soft-deleted. Defaults to "0s" (never). Format is a Go duration string.
          example: 0s
  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