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