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: string description: SQL statements to create the user revocation_statements: type: array items: type: string description: SQL statements to revoke the user default_ttl: type: string description: Default TTL for credentials max_ttl: type: string description: Maximum TTL for credentials CertificateResponse: type: object properties: data: type: object properties: certificate: type: string description: PEM-encoded certificate issuing_ca: type: string description: PEM-encoded issuing CA certificate ca_chain: type: array items: type: string description: Full CA chain private_key: type: string description: PEM-encoded private key private_key_type: type: string description: Type of private key (rsa, ec, ed25519) serial_number: type: string description: Certificate serial number expiration: type: integer description: Expiration time as Unix epoch PkiRole: type: object properties: allowed_domains: type: array items: type: string description: Allowed domain names allow_subdomains: type: boolean description: Whether subdomains are allowed allow_bare_domains: type: boolean description: Whether bare domains are allowed allow_glob_domains: type: boolean description: Whether glob patterns in domains are allowed allow_ip_sans: type: boolean description: Whether IP SANs are allowed max_ttl: type: string description: Maximum TTL for certificates ttl: type: string description: Default TTL for certificates key_type: type: string enum: - rsa - ec - ed25519 description: Key type for generated certificates key_bits: type: integer description: Number of bits for the key TransitKey: type: object properties: data: type: object properties: name: type: string description: Name of the key type: type: string description: Key type deletion_allowed: type: boolean description: Whether the key can be deleted derived: type: boolean description: Whether the key is derived exportable: type: boolean description: Whether the key is exportable allow_plaintext_backup: type: boolean description: Whether plaintext backup is allowed keys: type: object additionalProperties: type: integer description: Map of key version to creation time min_decryption_version: type: integer description: Minimum version for decryption min_encryption_version: type: integer description: Minimum version for encryption supports_encryption: type: boolean supports_decryption: type: boolean supports_derivation: type: boolean supports_signing: type: boolean auto_rotate_period: type: string description: Auto-rotation period latest_version: type: integer description: Latest key version