Vault Secrets Engines API
APIs for various secrets engines including Key/Value, AWS, Azure, databases, PKI, SSH, and more.
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: support@hashicorp.com
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