HashiCorp Vault
Vault Secrets Engines API

APIs for various secrets engines including Key/Value, AWS, Azure, databases, PKI, SSH, and more.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: HashiCorp Vault Vault Secrets Engines API
  description: >-
    APIs for various Vault secrets engines including the KV (Key/Value) v1 and v2
    engines, AWS dynamic credentials, database dynamic credentials, PKI
    certificate management, SSH certificate signing, and Transit
    encryption-as-a-service.
  version: '1.0'
  contact:
    name: HashiCorp Support
    email: [email protected]
    url: https://support.hashicorp.com/
  license:
    name: Business Source License 1.1
    url: https://github.com/hashicorp/vault/blob/main/LICENSE
externalDocs:
  description: Vault Secrets Engines API Documentation
  url: https://developer.hashicorp.com/vault/api-docs/secret
servers:
  - url: https://vault.example.com/v1
    description: Vault Server
tags:
  - name: AWS
    description: AWS dynamic credentials secrets engine
  - name: Database
    description: Database dynamic credentials secrets engine
  - name: KV V2
    description: Key/Value version 2 secrets engine
  - name: PKI
    description: PKI certificate management secrets engine
  - name: SSH
    description: SSH certificate signing secrets engine
  - name: Transit
    description: Transit encryption-as-a-service secrets engine
security:
  - vaultToken: []
paths:
  /{mount}/config:
    get:
      operationId: readKvV2Config
      summary: HashiCorp Vault Read KV v2 engine configuration
      description: >-
        Retrieves the configuration for the KV v2 secrets engine at the given
        mount path.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
      responses:
        '200':
          description: Configuration returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/KvV2Config'
        '403':
          description: Permission denied
    post:
      operationId: updateKvV2Config
      summary: HashiCorp Vault Configure KV v2 engine
      description: Configures backend-level settings for the KV v2 secrets engine.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KvV2Config'
      responses:
        '204':
          description: Configuration updated
        '403':
          description: Permission denied
  /{mount}/data/{path}:
    get:
      operationId: readKvV2Secret
      summary: HashiCorp Vault Read KV v2 secret
      description: >-
        Reads the value of the secret at the specified path. Returns the current
        version by default, or a specific version if the version parameter is
        provided.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
        - name: version
          in: query
          description: Version number to read
          schema:
            type: integer
      responses:
        '200':
          description: Secret data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KvV2ReadResponse'
        '403':
          description: Permission denied
        '404':
          description: Secret not found
    post:
      operationId: createOrUpdateKvV2Secret
      summary: HashiCorp Vault Create or update KV v2 secret
      description: >-
        Creates a new version of a secret at the specified path. If the secret
        does not exist, it will be created.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                options:
                  type: object
                  properties:
                    cas:
                      type: integer
                      description: Check-and-set value for optimistic concurrency
                data:
                  type: object
                  additionalProperties: true
                  description: The secret data to store
      responses:
        '200':
          description: Secret created or updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/KvV2VersionMetadata'
        '403':
          description: Permission denied
    delete:
      operationId: deleteLatestKvV2Secret
      summary: HashiCorp Vault Delete latest version of KV v2 secret
      description: >-
        Performs a soft delete of the latest version of the secret at the
        specified path. The data can be recovered using the undelete endpoint.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      responses:
        '204':
          description: Secret version soft-deleted
        '403':
          description: Permission denied
  /{mount}/delete/{path}:
    post:
      operationId: deleteKvV2SecretVersions
      summary: HashiCorp Vault Delete specific versions of KV v2 secret
      description: >-
        Performs a soft delete of the specified versions of a secret. The data
        can be recovered using the undelete endpoint.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - versions
              properties:
                versions:
                  type: array
                  items:
                    type: integer
                  description: Versions to soft-delete
      responses:
        '204':
          description: Secret versions soft-deleted
        '403':
          description: Permission denied
  /{mount}/undelete/{path}:
    post:
      operationId: undeleteKvV2SecretVersions
      summary: HashiCorp Vault Undelete versions of KV v2 secret
      description: Restores soft-deleted versions of a secret.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - versions
              properties:
                versions:
                  type: array
                  items:
                    type: integer
                  description: Versions to undelete
      responses:
        '204':
          description: Secret versions restored
        '403':
          description: Permission denied
  /{mount}/destroy/{path}:
    post:
      operationId: destroyKvV2SecretVersions
      summary: HashiCorp Vault Destroy versions of KV v2 secret
      description: >-
        Permanently destroys the specified versions of a secret. This action
        is irreversible.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - versions
              properties:
                versions:
                  type: array
                  items:
                    type: integer
                  description: Versions to permanently destroy
      responses:
        '204':
          description: Secret versions permanently destroyed
        '403':
          description: Permission denied
  /{mount}/metadata/{path}:
    get:
      operationId: readKvV2Metadata
      summary: HashiCorp Vault Read KV v2 secret metadata
      description: >-
        Returns metadata and version history for the secret at the specified path.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      responses:
        '200':
          description: Metadata returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KvV2MetadataResponse'
        '403':
          description: Permission denied
        '404':
          description: Secret not found
    post:
      operationId: updateKvV2Metadata
      summary: HashiCorp Vault Update KV v2 secret metadata
      description: Updates metadata settings for the secret at the specified path.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                max_versions:
                  type: integer
                  description: Maximum number of versions to keep
                cas_required:
                  type: boolean
                  description: Whether check-and-set is required
                delete_version_after:
                  type: string
                  description: Duration after which versions are deleted (e.g., 30d)
                custom_metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: Custom key-value metadata pairs
      responses:
        '204':
          description: Metadata updated
        '403':
          description: Permission denied
    delete:
      operationId: deleteKvV2Metadata
      summary: HashiCorp Vault Delete KV v2 secret metadata and all versions
      description: >-
        Permanently deletes the secret metadata and all version data for the
        specified path. This is irreversible.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
        - $ref: '#/components/parameters/secretPath'
      responses:
        '204':
          description: Metadata and all versions permanently deleted
        '403':
          description: Permission denied
  /{mount}/metadata/:
    get:
      operationId: listKvV2Secrets
      summary: HashiCorp Vault List KV v2 secrets
      description: Returns a list of secret keys at the specified path.
      tags:
        - KV V2
      parameters:
        - $ref: '#/components/parameters/kvMountPath'
      responses:
        '200':
          description: Secret keys listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      keys:
                        type: array
                        items:
                          type: string
                        description: List of secret keys
        '403':
          description: Permission denied
  /aws/creds/{name}:
    get:
      operationId: generateAwsCredentials
      summary: HashiCorp Vault Generate AWS credentials
      description: >-
        Generates dynamic AWS access credentials based on the named role.
      tags:
        - AWS
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      responses:
        '200':
          description: AWS credentials generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwsCredentialsResponse'
        '403':
          description: Permission denied
  /aws/roles/{name}:
    get:
      operationId: readAwsRole
      summary: HashiCorp Vault Read AWS role
      description: Reads the configuration for the named AWS role.
      tags:
        - AWS
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      responses:
        '200':
          description: AWS role configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwsRole'
        '404':
          description: Role not found
    post:
      operationId: createOrUpdateAwsRole
      summary: HashiCorp Vault Create or update AWS role
      description: Creates or updates the named AWS role.
      tags:
        - AWS
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwsRole'
      responses:
        '204':
          description: Role created or updated
        '400':
          description: Invalid request
    delete:
      operationId: deleteAwsRole
      summary: HashiCorp Vault Delete AWS role
      description: Deletes the named AWS role.
      tags:
        - AWS
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      responses:
        '204':
          description: Role deleted
  /database/creds/{name}:
    get:
      operationId: generateDatabaseCredentials
      summary: HashiCorp Vault Generate database credentials
      description: >-
        Generates dynamic database credentials based on the named role.
      tags:
        - Database
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the database role
          schema:
            type: string
      responses:
        '200':
          description: Database credentials generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseCredentialsResponse'
        '403':
          description: Permission denied
  /database/roles/{name}:
    get:
      operationId: readDatabaseRole
      summary: HashiCorp Vault Read database role
      description: Reads the configuration for the named database role.
      tags:
        - Database
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      responses:
        '200':
          description: Database role configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseRole'
        '404':
          description: Role not found
    post:
      operationId: createOrUpdateDatabaseRole
      summary: HashiCorp Vault Create or update database role
      description: Creates or updates the named database role.
      tags:
        - Database
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseRole'
      responses:
        '204':
          description: Role created or updated
        '400':
          description: Invalid request
    delete:
      operationId: deleteDatabaseRole
      summary: HashiCorp Vault Delete database role
      description: Deletes the named database role.
      tags:
        - Database
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the role
          schema:
            type: string
      responses:
        '204':
          description: Role deleted
  /pki/issue/{name}:
    post:
      operationId: issueCertificate
      summary: HashiCorp Vault Issue certificate
      description: >-
        Generates a new certificate based on the named role. The private key
        is returned in the response.
      tags:
        - PKI
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the PKI role
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - common_name
              properties:
                common_name:
                  type: string
                  description: Common name for the certificate
                alt_names:
                  type: string
                  description: Comma-separated SANs
                ip_sans:
                  type: string
                  description: Comma-separated IP SANs
                ttl:
                  type: string
                  description: Requested TTL (e.g., 24h)
                format:
                  type: string
                  enum:
                    - pem
                    - der
                    - pem_bundle
                  description: Output format
      responses:
        '200':
          description: Certificate issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '400':
          description: Invalid request
        '403':
          description: Permission denied
  /pki/ca:
    get:
      operationId: readCaCertificate
      summary: HashiCorp Vault Read CA certificate
      description: Returns the CA certificate in PEM format.
      tags:
        - PKI
      responses:
        '200':
          description: CA certificate returned
          content:
            application/pem-certificate-chain:
              schema:
                type: string
      security: []
  /pki/roles/{name}:
    get:
      operationId: readPkiRole
      summary: HashiCorp Vault Read PKI role
      description: Reads the configuration for the named PKI role.
      tags:
        - PKI
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the PKI role
          schema:
            type: string
      responses:
        '200':
          description: PKI role configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PkiRole'
        '404':
          description: Role not found
    post:
      operationId: createOrUpdatePkiRole
      summary: HashiCorp Vault Create or update PKI role
      description: Creates or updates the named PKI role.
      tags:
        - PKI
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the PKI role
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PkiRole'
      responses:
        '204':
          description: Role created or updated
        '400':
          description: Invalid request
  /transit/encrypt/{name}:
    post:
      operationId: encryptData
      summary: HashiCorp Vault Encrypt data
      description: >-
        Encrypts the provided plaintext using the named encryption key.
      tags:
        - Transit
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the encryption key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - plaintext
              properties:
                plaintext:
                  type: string
                  description: Base64-encoded plaintext to encrypt
                context:
                  type: string
                  description: Base64-encoded context for convergent encryption
                key_version:
                  type: integer
                  description: Version of the key to use
      responses:
        '200':
          description: Data encrypted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ciphertext:
                        type: string
                        description: Vault-prefixed ciphertext
                      key_version:
                        type: integer
        '400':
          description: Invalid request
        '403':
          description: Permission denied
  /transit/decrypt/{name}:
    post:
      operationId: decryptData
      summary: HashiCorp Vault Decrypt data
      description: Decrypts the provided ciphertext using the named encryption key.
      tags:
        - Transit
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the encryption key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ciphertext
              properties:
                ciphertext:
                  type: string
                  description: Vault-prefixed ciphertext to decrypt
                context:
                  type: string
                  description: Base64-encoded context for convergent encryption
      responses:
        '200':
          description: Data decrypted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      plaintext:
                        type: string
                        description: Base64-encoded plaintext
        '400':
          description: Invalid request
        '403':
          description: Permission denied
  /transit/keys/{name}:
    get:
      operationId: readTransitKey
      summary: HashiCorp Vault Read transit encryption key
      description: Returns information about the named encryption key.
      tags:
        - Transit
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the encryption key
          schema:
            type: string
      responses:
        '200':
          description: Key information returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransitKey'
        '404':
          description: Key not found
    post:
      operationId: createTransitKey
      summary: HashiCorp Vault Create transit encryption key
      description: Creates a new named encryption key.
      tags:
        - Transit
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the encryption key
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - aes128-gcm96
                    - aes256-gcm96
                    - chacha20-poly1305
                    - ed25519
                    - ecdsa-p256
                    - ecdsa-p384
                    - ecdsa-p521
                    - rsa-2048
                    - rsa-3072
                    - rsa-4096
                  description: Type of encryption key
                convergent_encryption:
                  type: boolean
                  description: Whether to enable convergent encryption
                derived:
                  type: boolean
                  description: Whether the key is derived from a context
                exportable:
                  type: boolean
                  description: Whether the key is exportable
                allow_plaintext_backup:
                  type: boolean
                  description: Whether plaintext backup is allowed
                auto_rotate_period:
                  type: string
                  description: Auto-rotation period (e.g., 24h)
      responses:
        '204':
          description: Key created
        '400':
          description: Invalid request
    delete:
      operationId: deleteTransitKey
      summary: HashiCorp Vault Delete transit encryption key
      description: >-
        Deletes the named encryption key. The key must have deletion allowed
        set to true.
      tags:
        - Transit
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the encryption key
          schema:
            type: string
      responses:
        '204':
          description: Key deleted
        '403':
          description: Permission denied
  /ssh/sign/{name}:
    post:
      operationId: signSshKey
      summary: HashiCorp Vault Sign SSH key
      description: Signs the provided public key using the named SSH role.
      tags:
        - SSH
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the SSH role
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - public_key
              properties:
                public_key:
                  type: string
                  description: SSH public key to sign
                valid_principals:
                  type: string
                  description: Comma-separated list of valid principals
                ttl:
                  type: string
                  description: Requested TTL
                cert_type:
                  type: string
                  enum:
                    - user
                    - host
                  description: Certificate type
      responses:
        '200':
          description: SSH key signed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      signed_key:
                        type: string
                        description: Signed SSH certificate
                      serial_number:
                        type: string
                        description: Certificate serial number
        '400':
          description: Invalid request
        '403':
          description: Permission denied
components:
  securitySchemes:
    vaultToken:
      type: apiKey
      in: header
      name: X-Vault-Token
      description: Vault authentication token
  parameters:
    kvMountPath:
      name: mount
      in: path
      required: true
      description: Mount path for the secrets engine (e.g., secret, kv)
      schema:
        type: string
        default: secret
    secretPath:
      name: path
      in: path
      required: true
      description: Path to the secret within the secrets engine
      schema:
        type: string
  schemas:
    KvV2Config:
      type: object
      properties:
        cas_required:
          type: boolean
          description: Whether check-and-set is required for all writes
        max_versions:
          type: integer
          description: Maximum number of versions to keep per key
        delete_version_after:
          type: string
          description: Duration after which versions are automatically deleted
    KvV2ReadResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            data:
              type: object
              additionalProperties: true
              description: The secret key-value data
            metadata:
              $ref: '#/components/schemas/KvV2VersionMetadata'
    KvV2VersionMetadata:
      type: object
      properties:
        created_time:
          type: string
          format: date-time
          description: When this version was created
        custom_metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom metadata key-value pairs
        deletion_time:
          type: string
          description: When this version was deleted (empty if not deleted)
        destroyed:
          type: boolean
          description: Whether this version has been permanently destroyed
        version:
          type: integer
          description: Version number
    KvV2MetadataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            cas_required:
              type: boolean
            created_time:
              type: string
              format: date-time
            current_version:
              type: integer
            custom_metadata:
              type: object
              additionalProperties:
                type: string
            delete_version_after:
              type: string
            max_versions:
              type: integer
            oldest_version:
              type: integer
            updated_time:
              type: string
              format: date-time
            versions:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/KvV2VersionMetadata'
    AwsCredentialsResponse:
      type: object
      properties:
        lease_id:
          type: string
          description: Unique lease identifier
        lease_duration:
          type: integer
          description: Lease duration in seconds
        renewable:
          type: boolean
          description: Whether the lease is renewable
        data:
          type: object
          properties:
            access_key:
              type: string
              description: AWS access key ID
            secret_key:
              type: string
              description: AWS secret access key
            security_token:
              type: string
              description: AWS STS session token (for assumed_role type)
    AwsRole:
      type: object
      properties:
        credential_type:
          type: string
          enum:
            - iam_user
            - assumed_role
            - federation_token
          description: Type of AWS credential to generate
        role_arns:
          type: array
          items:
            type: string
          description: ARNs of IAM roles to assume
        policy_arns:
          type: array
          items:
            type: string
          description: ARNs of IAM policies to attach
        policy_document:
          type: string
          description: Inline IAM policy document in JSON
        default_sts_ttl:
          type: string
          description: Default TTL for STS credentials
        max_sts_ttl:
          type: string
          description: Maximum TTL for STS credentials
    DatabaseCredentialsResponse:
      type: object
      properties:
        lease_id:
          type: string
          description: Unique lease identifier
        lease_duration:
          type: integer
          description: Lease duration in seconds
        renewable:
          type: boolean
          description: Whether the lease is renewable
        data:
          type: object
          properties:
            username:
              type: string
              description: Generated database username
            password:
              type: string
              description: Generated database password
    DatabaseRole:
      type: object
      properties:
        db_name:
          type: string
          description: Name of the database connection
        creation_statements:
          type: array
          items:
            type: s

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hvault/refs/heads/main/openapi/hvault-secrets-engines-openapi.yml
Vault Secrets Engines API

Documentation

Specifications

Other Resources

OpenAPI Specification
