HashiCorp Vault System API
System backend operations (init, seal, mounts, auth, audit)
OpenAPI Specification
openapi: 3.1.0
info:
title: HashiCorp Vault HTTP Auth - AppRole System API
description: The Vault HTTP API provides full access to Vault functionality via HTTP. Every aspect of Vault can be controlled via this API including secrets management, authentication, system configuration, identity, and policy management.
version: 1.15.0
contact:
name: HashiCorp
url: https://www.vaultproject.io/
license:
name: Business Source License 1.1
url: https://github.com/hashicorp/vault/blob/main/LICENSE
servers:
- url: https://127.0.0.1:8200/v1
description: Local Vault server
- url: https://{vault_host}:{port}/v1
description: Custom Vault server
variables:
vault_host:
default: 127.0.0.1
port:
default: '8200'
security:
- VaultToken: []
tags:
- name: System
description: System backend operations (init, seal, mounts, auth, audit)
paths:
/sys/init:
get:
operationId: getInitStatus
summary: Check initialization status
description: Returns the initialization status of Vault.
tags:
- System
security: []
responses:
'200':
description: Initialization status
content:
application/json:
schema:
type: object
properties:
initialized:
type: boolean
put:
operationId: initialize
summary: Initialize Vault
description: Initializes a new Vault with the specified number of key shares and threshold.
tags:
- System
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
secret_shares:
type: integer
description: Number of key shares to split the root key into
secret_threshold:
type: integer
description: Number of key shares required to reconstruct the root key
pgp_keys:
type: array
items:
type: string
description: PGP keys to encrypt the key shares
root_token_pgp_key:
type: string
recovery_shares:
type: integer
recovery_threshold:
type: integer
recovery_pgp_keys:
type: array
items:
type: string
responses:
'200':
description: Vault initialized
content:
application/json:
schema:
type: object
properties:
keys:
type: array
items:
type: string
keys_base64:
type: array
items:
type: string
root_token:
type: string
/sys/seal-status:
get:
operationId: getSealStatus
summary: Check seal status
description: Returns the seal status of the Vault.
tags:
- System
security: []
responses:
'200':
description: Seal status
content:
application/json:
schema:
$ref: '#/components/schemas/SealStatus'
/sys/seal:
put:
operationId: seal
summary: Seal the Vault
description: Seals the Vault. Requires sudo capability.
tags:
- System
responses:
'204':
description: Vault sealed
/sys/unseal:
put:
operationId: unseal
summary: Submit an unseal key
description: Enters a single unseal key share to progress the unsealing of the Vault.
tags:
- System
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
key:
type: string
description: A single unseal key share
reset:
type: boolean
description: Reset the unseal process
migrate:
type: boolean
responses:
'200':
description: Unseal progress
content:
application/json:
schema:
$ref: '#/components/schemas/SealStatus'
/sys/health:
get:
operationId: getHealth
summary: Health status
description: Returns the health status of the Vault node including whether it is initialized, sealed, and if it is the active node.
tags:
- System
security: []
parameters:
- name: standbyok
in: query
schema:
type: boolean
description: Return 200 for standby nodes too
- name: activecode
in: query
schema:
type: integer
description: Custom status code for active node
- name: standbycode
in: query
schema:
type: integer
description: Custom status code for standby node
- name: sealedcode
in: query
schema:
type: integer
description: Custom status code for sealed node
- name: uninitcode
in: query
schema:
type: integer
description: Custom status code for uninitialized node
responses:
'200':
description: Vault is healthy, initialized, and unsealed
content:
application/json:
schema:
$ref: '#/components/schemas/HealthStatus'
'429':
description: Node is unsealed and standby
'472':
description: Node is in data recovery mode
'473':
description: Node is in standby or perf standby
'501':
description: Node is not initialized
'503':
description: Node is sealed
/sys/mounts:
get:
operationId: listSecretEngines
summary: List mounted secrets engines
description: Returns all mounted secrets engines.
tags:
- System
responses:
'200':
description: Secrets engines
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/MountConfig'
/sys/mounts/{path}:
post:
operationId: enableSecretEngine
summary: Enable a secrets engine
description: Enables a new secrets engine at the given path.
tags:
- System
parameters:
- name: path
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
description: Secrets engine type (kv, pki, transit, etc.)
description:
type: string
config:
type: object
properties:
default_lease_ttl:
type: string
max_lease_ttl:
type: string
force_no_cache:
type: boolean
options:
type: object
properties:
version:
type: string
description: KV version (1 or 2)
responses:
'204':
description: Secrets engine enabled
delete:
operationId: disableSecretEngine
summary: Disable a secrets engine
description: Disables the mount point at the given path.
tags:
- System
parameters:
- name: path
in: path
required: true
schema:
type: string
responses:
'204':
description: Secrets engine disabled
/sys/auth:
get:
operationId: listAuthMethods
summary: List auth methods
description: Returns all enabled auth methods.
tags:
- System
responses:
'200':
description: Auth methods
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/MountConfig'
/sys/auth/{path}:
post:
operationId: enableAuthMethod
summary: Enable an auth method
description: Enables a new auth method at the given path.
tags:
- System
parameters:
- name: path
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
description: Auth method type (token, userpass, ldap, approle, etc.)
description:
type: string
config:
type: object
responses:
'204':
description: Auth method enabled
delete:
operationId: disableAuthMethod
summary: Disable an auth method
tags:
- System
parameters:
- name: path
in: path
required: true
schema:
type: string
responses:
'204':
description: Auth method disabled
/sys/audit:
get:
operationId: listAuditDevices
summary: List audit devices
tags:
- System
responses:
'200':
description: Audit devices
content:
application/json:
schema:
type: object
additionalProperties:
type: object
/sys/audit/{path}:
put:
operationId: enableAuditDevice
summary: Enable an audit device
tags:
- System
parameters:
- name: path
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
enum:
- file
- syslog
- socket
description:
type: string
options:
type: object
properties:
file_path:
type: string
responses:
'204':
description: Audit device enabled
delete:
operationId: disableAuditDevice
summary: Disable an audit device
tags:
- System
parameters:
- name: path
in: path
required: true
schema:
type: string
responses:
'204':
description: Audit device disabled
/sys/generate-root/attempt:
get:
operationId: getRootGenerationProgress
summary: Read root generation progress
tags:
- System
responses:
'200':
description: Root generation progress
content:
application/json:
schema:
type: object
properties:
started:
type: boolean
nonce:
type: string
progress:
type: integer
required:
type: integer
complete:
type: boolean
encoded_token:
type: string
encoded_root_token:
type: string
pgp_fingerprint:
type: string
otp_length:
type: integer
put:
operationId: startRootGeneration
summary: Start root token generation
tags:
- System
requestBody:
content:
application/json:
schema:
type: object
properties:
otp:
type: string
pgp_key:
type: string
responses:
'200':
description: Root generation started
delete:
operationId: cancelRootGeneration
summary: Cancel root token generation
tags:
- System
responses:
'204':
description: Root generation cancelled
/sys/leader:
get:
operationId: getLeader
summary: Get leader information
description: Returns the high availability status and current leader instance.
tags:
- System
responses:
'200':
description: Leader info
content:
application/json:
schema:
type: object
properties:
ha_enabled:
type: boolean
is_self:
type: boolean
active_time:
type: string
format: date-time
leader_address:
type: string
leader_cluster_address:
type: string
performance_standby:
type: boolean
performance_standby_last_remote_wal:
type: integer
/sys/wrapping/wrap:
post:
operationId: wrap
summary: Wrap data
description: Wraps the given data in a single-use wrapping token.
tags:
- System
parameters:
- name: X-Vault-Wrap-TTL
in: header
required: true
schema:
type: string
description: TTL for the wrapping token
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Wrapped response
content:
application/json:
schema:
$ref: '#/components/schemas/VaultResponse'
/sys/wrapping/unwrap:
post:
operationId: unwrap
summary: Unwrap data
description: Returns the original response inside the given wrapping token.
tags:
- System
requestBody:
content:
application/json:
schema:
type: object
properties:
token:
type: string
responses:
'200':
description: Unwrapped data
content:
application/json:
schema:
$ref: '#/components/schemas/VaultResponse'
components:
schemas:
MountConfig:
type: object
properties:
type:
type: string
description:
type: string
accessor:
type: string
config:
type: object
properties:
default_lease_ttl:
type: integer
max_lease_ttl:
type: integer
force_no_cache:
type: boolean
options:
type: object
local:
type: boolean
seal_wrap:
type: boolean
external_entropy_access:
type: boolean
VaultResponse:
type: object
properties:
request_id:
type: string
lease_id:
type: string
renewable:
type: boolean
lease_duration:
type: integer
data:
type: object
additionalProperties: true
wrap_info:
type: object
properties:
token:
type: string
accessor:
type: string
ttl:
type: integer
creation_time:
type: string
format: date-time
creation_path:
type: string
wrapped_accessor:
type: string
nullable: true
warnings:
type: array
items:
type: string
nullable: true
auth:
type: object
properties:
client_token:
type: string
accessor:
type: string
policies:
type: array
items:
type: string
token_policies:
type: array
items:
type: string
metadata:
type: object
additionalProperties:
type: string
lease_duration:
type: integer
renewable:
type: boolean
entity_id:
type: string
token_type:
type: string
orphan:
type: boolean
nullable: true
SealStatus:
type: object
properties:
type:
type: string
initialized:
type: boolean
sealed:
type: boolean
t:
type: integer
description: Threshold
n:
type: integer
description: Number of shares
progress:
type: integer
nonce:
type: string
version:
type: string
build_date:
type: string
migration:
type: boolean
cluster_name:
type: string
cluster_id:
type: string
recovery_seal:
type: boolean
storage_type:
type: string
HealthStatus:
type: object
properties:
initialized:
type: boolean
sealed:
type: boolean
standby:
type: boolean
performance_standby:
type: boolean
replication_performance_mode:
type: string
replication_dr_mode:
type: string
server_time_utc:
type: integer
version:
type: string
cluster_name:
type: string
cluster_id:
type: string
securitySchemes:
VaultToken:
type: apiKey
name: X-Vault-Token
in: header
description: Vault client token