HashiCorp System API

openapi: 3.0.2
info:
  title: HashiCorp Vault Auth System API
  description: HTTP API that gives you full access to Vault. All API routes are prefixed with `/v1/`.
  version: 1.9.3
  license:
    name: Mozilla Public License 2.0
    url: https://www.mozilla.org/en-US/MPL/2.0
tags:
- name: System
paths:
  /sys/audit:
    description: List the currently enabled audit backends.
    x-vault-sudo: true
    get:
      summary: HashiCorp List the enabled audit devices.
      operationId: getSysAudit
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/audit-hash/{path}:
    description: The hash of the given string via the given audit backend
    parameters:
    - name: path
      description: 'The name of the backend. Cannot be delimited. Example: "mysql"'
      in: path
      schema:
        type: string
      required: true
    post:
      summary: HashiCorp The hash of the given string via the given audit backend
      operationId: postSysAuditHashPath
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: string
      responses:
        '200':
          description: OK
  /sys/audit/{path}:
    description: Enable or disable audit backends.
    parameters:
    - name: path
      description: 'The name of the backend. Cannot be delimited. Example: "mysql"'
      in: path
      schema:
        type: string
      required: true
    x-vault-sudo: true
    post:
      summary: HashiCorp Enable a new audit device at the supplied path.
      operationId: postSysAuditPath
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: User-friendly description for this audit backend.
                local:
                  type: boolean
                  description: Mark the mount as a local mount, which is not replicated and is unaffected by replication.
                  default: false
                options:
                  type: object
                  description: Configuration options for the audit backend.
                  format: kvpairs
                type:
                  type: string
                  description: 'The type of the backend. Example: "mysql"'
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Disable the audit device at the given path.
      operationId: deleteSysAuditPath
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/auth:
    description: List the currently enabled credential backends.
    get:
      summary: HashiCorp List the currently enabled credential backends.
      operationId: getSysAuth
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/auth/{path}:
    description: Enable a new credential backend with a name.
    parameters:
    - name: path
      description: 'The path to mount to. Cannot be delimited. Example: "user"'
      in: path
      schema:
        type: string
      required: true
    x-vault-sudo: true
    post:
      summary: HashiCorp Enables a new auth method.
      description: 'After enabling, the auth method can be accessed and configured via the auth path specified as part of the URL. This auth path will be nested under the auth prefix.


        For example, enable the "foo" auth method will make it accessible at /auth/foo.'
      operationId: postSysAuthPath
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  type: object
                  description: Configuration for this mount, such as plugin_name.
                  format: map
                description:
                  type: string
                  description: User-friendly description for this credential backend.
                external_entropy_access:
                  type: boolean
                  description: Whether to give the mount access to Vault's external entropy.
                  default: false
                local:
                  type: boolean
                  description: Mark the mount as a local mount, which is not replicated and is unaffected by replication.
                  default: false
                options:
                  type: object
                  description: The options to pass into the backend. Should be a json object with string keys and values.
                  format: kvpairs
                plugin_name:
                  type: string
                  description: Name of the auth plugin to use based from the name in the plugin catalog.
                seal_wrap:
                  type: boolean
                  description: Whether to turn on seal wrapping for the mount.
                  default: false
                type:
                  type: string
                  description: 'The type of the backend. Example: "userpass"'
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Disable the auth method at the given auth path
      operationId: deleteSysAuthPath
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/auth/{path}/tune:
    description: Tune the configuration parameters for an auth path.
    parameters:
    - name: path
      description: Tune the configuration parameters for an auth path.
      in: path
      schema:
        type: string
      required: true
    x-vault-sudo: true
    get:
      summary: HashiCorp Reads the given auth path's configuration.
      description: This endpoint requires sudo capability on the final path, but the same functionality can be achieved without sudo via `sys/mounts/auth/[auth-path]/tune`.
      operationId: getSysAuthPathTune
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Tune configuration parameters for a given auth path.
      description: This endpoint requires sudo capability on the final path, but the same functionality can be achieved without sudo via `sys/mounts/auth/[auth-path]/tune`.
      operationId: postSysAuthPathTune
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                allowed_response_headers:
                  type: array
                  description: A list of headers to whitelist and allow a plugin to set on responses.
                  items:
                    type: string
                audit_non_hmac_request_keys:
                  type: array
                  description: The list of keys in the request data object that will not be HMAC'ed by audit devices.
                  items:
                    type: string
                audit_non_hmac_response_keys:
                  type: array
                  description: The list of keys in the response data object that will not be HMAC'ed by audit devices.
                  items:
                    type: string
                default_lease_ttl:
                  type: string
                  description: The default lease TTL for this mount.
                description:
                  type: string
                  description: User-friendly description for this credential backend.
                listing_visibility:
                  type: string
                  description: Determines the visibility of the mount in the UI-specific listing endpoint. Accepted value are 'unauth' and ''.
                max_lease_ttl:
                  type: string
                  description: The max lease TTL for this mount.
                options:
                  type: object
                  description: The options to pass into the backend. Should be a json object with string keys and values.
                  format: kvpairs
                passthrough_request_headers:
                  type: array
                  description: A list of headers to whitelist and pass from the request to the plugin.
                  items:
                    type: string
                token_type:
                  type: string
                  description: The type of token to issue (service or batch).
      responses:
        '200':
          description: OK
  /sys/capabilities:
    description: Fetches the capabilities of the given token on the given path.
    post:
      summary: HashiCorp Fetches the capabilities of the given token on the given path.
      operationId: postSysCapabilities
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: array
                  description: Use 'paths' instead.
                  items:
                    type: string
                  deprecated: true
                paths:
                  type: array
                  description: Paths on which capabilities are being queried.
                  items:
                    type: string
                token:
                  type: string
                  description: Token for which capabilities are being queried.
      responses:
        '200':
          description: OK
  /sys/capabilities-accessor:
    description: Fetches the capabilities of the token associated with the given token, on the given path.
    post:
      summary: HashiCorp Fetches the capabilities of the token associated with the given token, on the given path.
      operationId: postSysCapabilitiesAccessor
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessor:
                  type: string
                  description: Accessor of the token for which capabilities are being queried.
                path:
                  type: array
                  description: Use 'paths' instead.
                  items:
                    type: string
                  deprecated: true
                paths:
                  type: array
                  description: Paths on which capabilities are being queried.
                  items:
                    type: string
      responses:
        '200':
          description: OK
  /sys/capabilities-self:
    description: Fetches the capabilities of the given token on the given path.
    post:
      summary: HashiCorp Fetches the capabilities of the given token on the given path.
      operationId: postSysCapabilitiesSelf
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: array
                  description: Use 'paths' instead.
                  items:
                    type: string
                  deprecated: true
                paths:
                  type: array
                  description: Paths on which capabilities are being queried.
                  items:
                    type: string
                token:
                  type: string
                  description: Token for which capabilities are being queried.
      responses:
        '200':
          description: OK
  /sys/config/auditing/request-headers:
    description: Lists the headers configured to be audited.
    x-vault-sudo: true
    get:
      summary: HashiCorp List the request headers that are configured to be audited.
      operationId: getSysConfigAuditingRequestHeaders
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/config/auditing/request-headers/{header}:
    description: Configures the headers sent to the audit logs.
    parameters:
    - name: header
      in: path
      schema:
        type: string
      required: true
    x-vault-sudo: true
    get:
      summary: HashiCorp List the information for the given request header.
      operationId: getSysConfigAuditingRequestHeadersHeader
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Enable auditing of a header.
      operationId: postSysConfigAuditingRequestHeadersHeader
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hmac:
                  type: boolean
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Disable auditing of the given request header.
      operationId: deleteSysConfigAuditingRequestHeadersHeader
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/config/cors:
    description: This path responds to the following HTTP methods. GET / Returns the configuration of the CORS setting. POST / Sets the comma-separated list of origins that can make cross-origin requests. DELETE / Clears the CORS configuration and disables acceptance of CORS requests.
    x-vault-sudo: true
    get:
      summary: HashiCorp Return the current CORS settings.
      operationId: getSysConfigCors
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Configure the CORS settings.
      operationId: postSysConfigCors
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                allowed_headers:
                  type: array
                  description: A comma-separated string or array of strings indicating headers that are allowed on cross-origin requests.
                  items:
                    type: string
                allowed_origins:
                  type: array
                  description: A comma-separated string or array of strings indicating origins that may make cross-origin requests.
                  items:
                    type: string
                enable:
                  type: boolean
                  description: Enables or disables CORS headers on requests.
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Remove any CORS settings.
      operationId: deleteSysConfigCors
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/config/reload/{subsystem}:
    parameters:
    - name: subsystem
      in: path
      schema:
        type: string
      required: true
    post:
      summary: HashiCorp Reload the given subsystem
      operationId: postSysConfigReloadSubsystem
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/config/state/sanitized:
    get:
      summary: HashiCorp Return a sanitized version of the Vault server configuration.
      description: The sanitized output strips configuration values in the storage, HA storage, and seals stanzas, which may contain sensitive values such as API tokens. It also removes any token or secret fields in other stanzas, such as the circonus_api_token from telemetry.
      operationId: getSysConfigStateSanitized
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/config/ui/headers/:
    description: This path responds to the following HTTP methods. GET /<header> Returns the header value. POST /<header> Sets the header value for the UI. DELETE /<header> Clears the header value for UI. LIST / List the headers configured for the UI.
    x-vault-sudo: true
    get:
      summary: HashiCorp Return a list of configured UI headers.
      operationId: getSysConfigUiHeaders
      tags:
      - System
      parameters:
      - name: list
        description: Return a list if `true`
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
  /sys/config/ui/headers/{header}:
    description: This path responds to the following HTTP methods. GET /<header> Returns the header value. POST /<header> Sets the header value for the UI. DELETE /<header> Clears the header value for UI. LIST / List the headers configured for the UI.
    parameters:
    - name: header
      description: The name of the header.
      in: path
      schema:
        type: string
      required: true
    x-vault-sudo: true
    get:
      summary: HashiCorp Return the given UI header's configuration
      operationId: getSysConfigUiHeadersHeader
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Configure the values to be returned for the UI header.
      operationId: postSysConfigUiHeadersHeader
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                multivalue:
                  type: boolean
                  description: Returns multiple values if true
                values:
                  type: array
                  description: The values to set the header.
                  items:
                    type: string
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Remove a UI header.
      operationId: deleteSysConfigUiHeadersHeader
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/generate-root:
    description: Reads, generates, or deletes a root token regeneration process.
    get:
      summary: HashiCorp Read the configuration and progress of the current root generation attempt.
      operationId: getSysGenerateRoot
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Initializes a new root generation attempt.
      description: Only a single root generation attempt can take place at a time. One (and only one) of otp or pgp_key are required.
      operationId: postSysGenerateRoot
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                pgp_key:
                  type: string
                  description: Specifies a base64-encoded PGP public key.
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Cancels any in-progress root generation attempt.
      operationId: deleteSysGenerateRoot
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/generate-root/attempt:
    description: Reads, generates, or deletes a root token regeneration process.
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Read the configuration and progress of the current root generation attempt.
      operationId: getSysGenerateRootAttempt
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Initializes a new root generation attempt.
      description: Only a single root generation attempt can take place at a time. One (and only one) of otp or pgp_key are required.
      operationId: postSysGenerateRootAttempt
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                pgp_key:
                  type: string
                  description: Specifies a base64-encoded PGP public key.
      responses:
        '200':
          description: OK
    delete:
      summary: HashiCorp Cancels any in-progress root generation attempt.
      operationId: deleteSysGenerateRootAttempt
      tags:
      - System
      responses:
        '204':
          description: empty body
  /sys/generate-root/update:
    description: Reads, generates, or deletes a root token regeneration process.
    x-vault-unauthenticated: true
    post:
      summary: HashiCorp Enter a single master key share to progress the root generation attempt.
      description: If the threshold number of master key shares is reached, Vault will complete the root generation and issue the new token. Otherwise, this API must be called multiple times until that threshold is met. The attempt nonce must be provided with each call.
      operationId: postSysGenerateRootUpdate
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                  description: Specifies a single master key share.
                nonce:
                  type: string
                  description: Specifies the nonce of the attempt.
      responses:
        '200':
          description: OK
  /sys/health:
    description: Checks the health status of the Vault.
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Returns the health status of Vault.
      operationId: getSysHealth
      tags:
      - System
      responses:
        '200':
          description: initialized, unsealed, and active
        '429':
          description: unsealed and standby
        '472':
          description: data recovery mode replication secondary and active
        '501':
          description: not initialized
        '503':
          description: sealed
  /sys/host-info:
    description: Information about the host instance that this Vault server is running on.
    get:
      summary: HashiCorp Information about the host instance that this Vault server is running on.
      description: "Information about the host instance that this Vault server is running on.\n\t\tThe information that gets collected includes host hardware information, and CPU,\n\t\tdisk, and memory utilization"
      operationId: getSysHostInfo
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/init:
    description: Initializes or returns the initialization status of the Vault.
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Returns the initialization status of Vault.
      operationId: getSysInit
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Initialize a new Vault.
      description: The Vault must not have been previously initialized. The recovery options, as well as the stored shares option, are only available when using Vault HSM.
      operationId: postSysInit
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                pgp_keys:
                  type: array
                  description: Specifies an array of PGP public keys used to encrypt the output unseal keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as `secret_shares`.
                  items:
                    type: string
                recovery_pgp_keys:
                  type: array
                  description: Specifies an array of PGP public keys used to encrypt the output recovery keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as `recovery_shares`.
                  items:
                    type: string
                recovery_shares:
                  type: integer
                  description: Specifies the number of shares to split the recovery key into.
                recovery_threshold:
                  type: integer
                  description: Specifies the number of shares required to reconstruct the recovery key. This must be less than or equal to `recovery_shares`.
                root_token_pgp_key:
                  type: string
                  description: Specifies a PGP public key used to encrypt the initial root token. The key must be base64-encoded from its original binary representation.
                secret_shares:
                  type: integer
                  description: Specifies the number of shares to split the master key into.
                secret_threshold:
                  type: integer
                  description: Specifies the number of shares required to reconstruct the master key. This must be less than or equal secret_shares. If using Vault HSM with auto-unsealing, this value must be the same as `secret_shares`.
                stored_shares:
                  type: integer
                  description: Specifies the number of shares that should be encrypted by the HSM and stored for auto-unsealing. Currently must be the same as `secret_shares`.
      responses:
        '200':
          description: OK
  /sys/internal/counters/activity:
    description: Query the historical count of clients.
    get:
      summary: HashiCorp Report the client count metrics, for this namespace and all child namespaces.
      operationId: getSysInternalCountersActivity
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/counters/activity/monthly:
    description: Count of active clients so far this month.
    get:
      summary: HashiCorp Report the number of clients for this month, for this namespace and all child namespaces.
      operationId: getSysInternalCountersActivityMonthly
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/counters/config:
    description: Control the collection and reporting of client counts.
    get:
      summary: HashiCorp Read the client count tracking configuration.
      operationId: getSysInternalCountersConfig
      tags:
      - System
      responses:
        '200':
          description: OK
    post:
      summary: HashiCorp Enable or disable collection of client count, set retention period, or set default reporting period.
      operationId: postSysInternalCountersConfig
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                default_report_months:
                  type: integer
                  description: Number of months to report if no start date specified.
                  default: 12
                enabled:
                  type: string
                  description: 'Enable or disable collection of client count: enable, disable, or default.'
                  default: default
                retention_months:
                  type: integer
                  description: Number of months of client data to retain. Setting to 0 will clear all existing data.
                  default: 24
      responses:
        '200':
          description: OK
  /sys/internal/counters/entities:
    description: Count of active entities in this Vault cluster.
    get:
      summary: HashiCorp Backwards compatibility is not guaranteed for this API
      operationId: getSysInternalCountersEntities
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/counters/requests:
    description: Currently unsupported. Previously, count of requests seen by this Vault cluster over time.
    get:
      summary: HashiCorp Backwards compatibility is not guaranteed for this API
      operationId: getSysInternalCountersRequests
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/counters/tokens:
    description: Count of active tokens in this Vault cluster.
    get:
      summary: HashiCorp Backwards compatibility is not guaranteed for this API
      operationId: getSysInternalCountersTokens
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/specs/openapi:
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Generate an OpenAPI 3 document of all mounted paths.
      operationId: getSysInternalSpecsOpenapi
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/ui/feature-flags:
    description: Enabled feature flags. Internal API; its location, inputs, and outputs may change.
    get:
      summary: HashiCorp Lists enabled feature flags.
      operationId: getSysInternalUiFeatureFlags
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/ui/mounts:
    description: Information about mounts returned according to their tuned visibility. Internal API; its location, inputs, and outputs may change.
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Lists all enabled and visible auth and secrets mounts.
      operationId: getSysInternalUiMounts
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/ui/mounts/{path}:
    description: Information about mounts returned according to their tuned visibility. Internal API; its location, inputs, and outputs may change.
    parameters:
    - name: path
      description: The path of the mount.
      in: path
      schema:
        type: string
      required: true
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Return information about the given mount.
      operationId: getSysInternalUiMountsPath
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/ui/namespaces:
    description: Information about visible child namespaces. Internal API; its location, inputs, and outputs may change.
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Backwards compatibility is not guaranteed for this API
      operationId: getSysInternalUiNamespaces
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/internal/ui/resultant-acl:
    description: Information about a token's resultant ACL. Internal API; its location, inputs, and outputs may change.
    get:
      summary: HashiCorp Backwards compatibility is not guaranteed for this API
      operationId: getSysInternalUiResultantAcl
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/key-status:
    description: Provides information about the backend encryption key.
    get:
      summary: HashiCorp Provides information about the backend encryption key.
      operationId: getSysKeyStatus
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/leader:
    description: Check the high availability status and current leader of Vault
    x-vault-unauthenticated: true
    get:
      summary: HashiCorp Returns the high availability status and current leader instance of Vault.
      operationId: getSysLeader
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/leases:
    description: List leases associated with this Vault cluster
    x-vault-sudo: true
    get:
      summary: HashiCorp List leases associated with this Vault cluster
      operationId: getSysLeases
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/leases/count:
    description: Count of leases associated with this Vault cluster
    get:
      summary: HashiCorp Count of leases associated with this Vault cluster
      operationId: getSysLeasesCount
      tags:
      - System
      responses:
        '200':
          description: OK
  /sys/leases/lookup:
    description: View or list lease metadata.
    post:
      summary: HashiCorp Retrieve lease metadata.
      operationId: postSysLeasesLookup
      tags:
      - System
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                lease_id:
                  type: string
                  description: The lease identifier to renew. This is included with a lease.
      responses:
        '200':
          description: OK
  /sys/leases/lookup/:
    description: View or list lease metadata.
    x-vault-sudo: true
    get:
      summary: HashiCorp Returns a list of lease ids.
      operationId: getSysLeasesLookup
      tags:
      - System
      paramet

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hashicorp/refs/heads/main/openapi/hashicorp-system-api-openapi.yml