hvac.api.system_backend

Collection of Vault system backend API endpoint classes.

class hvac.api.system_backend.Audit(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

calculate_hash(path, input_to_hash)[source]

Hash the given input data with the specified audit device’s hash function and salt.

This endpoint can be used to discover whether a given plaintext string (the input parameter) appears in the audit log in obfuscated form.

Supported methods:
POST: /sys/audit-hash/{path}. Produces: 204 (empty body)
Parameters:
  • path (str | unicode) – The path of the audit device to generate hashes for. This is part of the request URL.
  • input_to_hash (str | unicode) – The input string to hash.
Returns:

The JSON response of the request.

Return type:

requests.Response

disable_audit_device(path)[source]

Disable the audit device at the given path.

Supported methods:
DELETE: /sys/audit/{path}. Produces: 204 (empty body)
Parameters:path (str | unicode) – The path of the audit device to delete. This is part of the request URL.
Returns:The response of the request.
Return type:requests.Response
enable_audit_device(device_type, description=None, options=None, path=None)[source]

Enable a new audit device at the supplied path.

The path can be a single word name or a more complex, nested path.

Supported methods:
PUT: /sys/audit/{path}. Produces: 204 (empty body)
Parameters:
  • device_type (str | unicode) – Specifies the type of the audit device.
  • description (str | unicode) – Human-friendly description of the audit device.
  • options (str | unicode) – Configuration options to pass to the audit device itself. This is dependent on the audit device type.
  • path (str | unicode) – Specifies the path in which to enable the audit device. This is part of the request URL.
Returns:

The response of the request.

Return type:

requests.Response

list_enabled_audit_devices()[source]

List enabled audit devices.

It does not list all available audit devices. This endpoint requires sudo capability in addition to any path-specific capabilities.

Supported methods:
GET: /sys/audit. Produces: 200 application/json
Returns:JSON response of the request.
Return type:dict
class hvac.api.system_backend.Auth(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

disable_auth_method(path)[source]

Disable the auth method at the given auth path.

Supported methods:
DELETE: /sys/auth/{path}. Produces: 204 (empty body)
Parameters:path (str | unicode) – The path the method was mounted on. If not provided, defaults to the value of the “method_type” argument.
Returns:The response of the request.
Return type:requests.Response
enable_auth_method(method_type, description=None, config=None, plugin_name=None, local=False, path=None, **kwargs)[source]

Enable a new auth method.

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.

Supported methods:
POST: /sys/auth/{path}. Produces: 204 (empty body)
Parameters:
  • method_type (str | unicode) – The name of the authentication method type, such as “github” or “token”.
  • description (str | unicode) – A human-friendly description of the auth method.
  • config (dict) –

    Configuration options for this auth method. These are the possible values:

    • default_lease_ttl: The default lease duration, specified as a string duration like “5s” or “30m”.
    • max_lease_ttl: The maximum lease duration, specified as a string duration like “5s” or “30m”.
    • audit_non_hmac_request_keys: Comma-separated list of keys that will not be HMAC’d by audit devices in the request data object.
    • audit_non_hmac_response_keys: Comma-separated list of keys that will not be HMAC’d by audit devices in the response data object.
    • listing_visibility: Speficies whether to show this mount in the UI-specific listing endpoint.
    • passthrough_request_headers: Comma-separated list of headers to whitelist and pass from the request to the backend.
  • plugin_name (str | unicode) – The name of the auth plugin to use based from the name in the plugin catalog. Applies only to plugin methods.
  • local (bool) – <Vault enterprise only> Specifies if the auth method is a local only. Local auth methods are not replicated nor (if a secondary) removed by replication.
  • path (str | unicode) – The path to mount the method on. If not provided, defaults to the value of the “method_type” argument.
  • kwargs (dict) – All dicts are accepted and passed to vault. See your specific secret engine for details on which extra key-word arguments you might want to pass.
Returns:

The response of the request.

Return type:

requests.Response

list_auth_methods()[source]

List all enabled auth methods.

Supported methods:
GET: /sys/auth. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
read_auth_method_tuning(path)[source]

Read the given auth path’s configuration.

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.

Supported methods:
GET: /sys/auth/{path}/tune. Produces: 200 application/json
Parameters:path (str | unicode) – The path the method was mounted on. If not provided, defaults to the value of the “method_type” argument.
Returns:The JSON response of the request.
Return type:dict
tune_auth_method(path, default_lease_ttl=None, max_lease_ttl=None, description=None, audit_non_hmac_request_keys=None, audit_non_hmac_response_keys=None, listing_visibility='', passthrough_request_headers=None, **kwargs)[source]

Tune configuration parameters for a given auth path.

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.

Supported methods:
POST: /sys/auth/{path}/tune. Produces: 204 (empty body)
Parameters:
  • path (str | unicode) – The path the method was mounted on. If not provided, defaults to the value of the “method_type” argument.
  • default_lease_ttl (int) – Specifies the default time-to-live. If set on a specific auth path, this overrides the global default.
  • max_lease_ttl (int) – The maximum time-to-live. If set on a specific auth path, this overrides the global default.
  • description (str | unicode) – Specifies the description of the mount. This overrides the current stored value, if any.
  • audit_non_hmac_request_keys (array) – Specifies the list of keys that will not be HMAC’d by audit devices in the request data object.
  • audit_non_hmac_response_keys (list) – Specifies the list of keys that will not be HMAC’d by audit devices in the response data object.
  • listing_visibility (list) – Specifies whether to show this mount in the UI-specific listing endpoint. Valid values are “unauth” or “”.
  • passthrough_request_headers (list) – List of headers to whitelist and pass from the request to the backend.
  • kwargs (dict) – All dicts are accepted and passed to vault. See your specific secret engine for details on which extra key-word arguments you might want to pass.
Returns:

The response of the request.

Return type:

requests.Response

class hvac.api.system_backend.Capabilities(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

get_capabilities(paths, token=None, accessor=None)[source]

Get the capabilities associated with a token.

Supported methods:
POST: /sys/capabilities-self. Produces: 200 application/json POST: /sys/capabilities. Produces: 200 application/json POST: /sys/capabilities-accessor. Produces: 200 application/json
Parameters:
  • paths (List[str]) – Paths on which capabilities are being queried.
  • token (str) – Token for which capabilities are being queried.
  • accessor (str) – Accessor of the token for which capabilities are being queried.
Returns:

The JSON response of the request.

Return type:

dict

class hvac.api.system_backend.Health(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

.

Reference: https://www.vaultproject.io/api/system/index.html

read_health_status(standby_ok=False, active_code=200, standby_code=429, dr_secondary_code=472, performance_standby_code=473, sealed_code=503, uninit_code=501, method='HEAD')[source]

Read the health status of Vault.

This matches the semantics of a Consul HTTP health check and provides a simple way to monitor the health of a Vault instance.

Parameters:
  • standby_ok (bool) – Specifies if being a standby should still return the active status code instead of the standby status code. This is useful when Vault is behind a non-configurable load balance that just wants a 200-level response.
  • active_code (int) – The status code that should be returned for an active node.
  • standby_code (int) – Specifies the status code that should be returned for a standby node.
  • dr_secondary_code (int) – Specifies the status code that should be returned for a DR secondary node.
  • performance_standby_code (int) – Specifies the status code that should be returned for a performance standby node.
  • sealed_code (int) – Specifies the status code that should be returned for a sealed node.
  • uninit_code (int) – Specifies the status code that should be returned for a uninitialized node.
  • method (str | unicode) – Supported methods: HEAD: /sys/health. Produces: 000 (empty body) GET: /sys/health. Produces: 000 application/json
Returns:

The JSON response of the request.

Return type:

requests.Response

class hvac.api.system_backend.Init(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

initialize(secret_shares=5, secret_threshold=3, pgp_keys=None, root_token_pgp_key=None, stored_shares=None, recovery_shares=None, recovery_threshold=None, recovery_pgp_keys=None)[source]

Initialize a new Vault.

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.

Supported methods:
PUT: /sys/init. Produces: 200 application/json
Parameters:
  • secret_shares (int) – The number of shares to split the master key into.
  • secret_threshold (int) – 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.
  • pgp_keys (list) – List 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.
  • root_token_pgp_key (str | unicode) – Specifies a PGP public key used to encrypt the initial root token. The key must be base64-encoded from its original binary representation.
  • stored_shares (int) – <enterprise only> 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.
  • recovery_shares (int) – <enterprise only> Specifies the number of shares to split the recovery key into.
  • recovery_threshold (int) – <enterprise only> Specifies the number of shares required to reconstruct the recovery key. This must be less than or equal to recovery_shares.
  • recovery_pgp_keys (list) – <enterprise only> 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.
Returns:

The JSON response of the request.

Return type:

dict

is_initialized()[source]

Determine is Vault is initialized or not.

Returns:True if Vault is initialized, False otherwise.
Return type:bool
read_init_status()[source]

Read the initialization status of Vault.

Supported methods:
GET: /sys/init. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
class hvac.api.system_backend.Key(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

cancel_rekey(recovery_key=False)[source]

Cancel any in-progress rekey.

This clears the rekey settings as well as any progress made. This must be called to change the parameters of the rekey.

Note: Verification is still a part of a rekey. If rekeying is canceled during the verification flow, the current unseal keys remain valid.

Supported methods:
DELETE: /sys/rekey/init. Produces: 204 (empty body) DELETE: /sys/rekey-recovery-key/init. Produces: 204 (empty body)
Parameters:recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:The response of the request.
Return type:requests.Response
cancel_root_generation()[source]

Cancel any in-progress root generation attempt.

This clears any progress made. This must be called to change the OTP or PGP key being used.

Supported methods:
DELETE: /sys/generate-root/attempt. Produces: 204 (empty body)
Returns:The response of the request.
Return type:request.Response
generate_root(key, nonce)[source]

Enter a single master key share to progress the root generation attempt.

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.

Supported methods:
PUT: /sys/generate-root/update. Produces: 200 application/json
Parameters:
  • key (str | unicode) – Specifies a single master key share.
  • nonce (str | unicode) – The nonce of the attempt.
Returns:

The JSON response of the request.

Return type:

dict

get_encryption_key_status()[source]

Read information about the current encryption key used by Vault.

Supported methods:
GET: /sys/key-status. Produces: 200 application/json
Returns:JSON response with information regarding the current encryption key used by Vault.
Return type:dict
read_backup_keys(recovery_key=False)[source]

Retrieve the backup copy of PGP-encrypted unseal keys.

The returned value is the nonce of the rekey operation and a map of PGP key fingerprint to hex-encoded PGP-encrypted key.

Supported methods:
PUT: /sys/rekey/backup. Produces: 200 application/json PUT: /sys/rekey-recovery-key/backup. Produces: 200 application/json
Parameters:recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:The JSON response of the request.
Return type:dict
read_rekey_progress(recovery_key=False)[source]

Read the configuration and progress of the current rekey attempt.

Supported methods:
GET: /sys/rekey-recovery-key/init. Produces: 200 application/json GET: /sys/rekey/init. Produces: 200 application/json
Parameters:recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:The JSON response of the request.
Return type:requests.Response
read_root_generation_progress()[source]

Read the configuration and process of the current root generation attempt.

Supported methods:
GET: /sys/generate-root/attempt. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
rekey(key, nonce=None, recovery_key=False)[source]

Enter a single recovery key share to progress the rekey of the Vault.

If the threshold number of recovery key shares is reached, Vault will complete the rekey. Otherwise, this API must be called multiple times until that threshold is met. The rekey nonce operation must be provided with each call.

Supported methods:
PUT: /sys/rekey/update. Produces: 200 application/json PUT: /sys/rekey-recovery-key/update. Produces: 200 application/json
Parameters:
  • key (str | unicode) – Specifies a single recovery share key.
  • nonce (str | unicode) – Specifies the nonce of the rekey operation.
  • recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:

The JSON response of the request.

Return type:

dict

rekey_multi(keys, nonce=None, recovery_key=False)[source]

Enter multiple recovery key shares to progress the rekey of the Vault.

If the threshold number of recovery key shares is reached, Vault will complete the rekey.

Parameters:
  • keys (list) – Specifies multiple recovery share keys.
  • nonce (str | unicode) – Specifies the nonce of the rekey operation.
  • recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:

The last response of the rekey request.

Return type:

response.Request

rotate_encryption_key()[source]

Trigger a rotation of the backend encryption key.

This is the key that is used to encrypt data written to the storage backend, and is not provided to operators. This operation is done online. Future values are encrypted with the new key, while old values are decrypted with previous encryption keys.

This path requires sudo capability in addition to update.

Supported methods:
PUT: /sys/rorate. Produces: 204 (empty body)
Returns:The response of the request.
Return type:requests.Response
start_rekey(secret_shares=5, secret_threshold=3, pgp_keys=None, backup=False, require_verification=False, recovery_key=False)[source]

Initializes a new rekey attempt.

Only a single recovery key rekeyattempt can take place at a time, and changing the parameters of a rekey requires canceling and starting a new rekey, which will also provide a new nonce.

Supported methods:
PUT: /sys/rekey/init. Produces: 204 (empty body) PUT: /sys/rekey-recovery-key/init. Produces: 204 (empty body)
Parameters:
  • secret_shares (int) – Specifies the number of shares to split the master key into.
  • secret_threshold (int) – Specifies the number of shares required to reconstruct the master key. This must be less than or equal to secret_shares.
  • pgp_keys (list) – 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.
  • backup (bool) – Specifies if using PGP-encrypted keys, whether Vault should also store a plaintext backup of the PGP-encrypted keys at core/unseal-keys-backup in the physical storage backend. These can then be retrieved and removed via the sys/rekey/backup endpoint.
  • require_verification (bool) – This turns on verification functionality. When verification is turned on, after successful authorization with the current unseal keys, the new unseal keys are returned but the master key is not actually rotated. The new keys must be provided to authorize the actual rotation of the master key. This ensures that the new keys have been successfully saved and protects against a risk of the keys being lost after rotation but before they can be persisted. This can be used with without pgp_keys, and when used with it, it allows ensuring that the returned keys can be successfully decrypted before committing to the new shares, which the backup functionality does not provide.
  • recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:

The JSON dict of the response.

Return type:

dict | request.Response

start_root_token_generation(otp=None, pgp_key=None)[source]

Initialize a new root generation attempt.

Only a single root generation attempt can take place at a time. One (and only one) of otp or pgp_key are required.

Supported methods:
PUT: /sys/generate-root/attempt. Produces: 200 application/json
Parameters:
  • otp (str | unicode) – Specifies a base64-encoded 16-byte value. The raw bytes of the token will be XOR’d with this value before being returned to the final unseal key provider.
  • pgp_key (str | unicode) – Specifies a base64-encoded PGP public key. The raw bytes of the token will be encrypted with this value before being returned to the final unseal key provider.
Returns:

The JSON response of the request.

Return type:

dict

class hvac.api.system_backend.Leader(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

read_leader_status()[source]

Read the high availability status and current leader instance of Vault.

Supported methods:
GET: /sys/leader. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
class hvac.api.system_backend.Lease(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

list_leases(prefix)[source]

Retrieve a list of lease ids.

Supported methods:
LIST: /sys/leases/lookup/{prefix}. Produces: 200 application/json
Parameters:prefix (str | unicode) – Lease prefix to filter list by.
Returns:The JSON response of the request.
Return type:dict
read_lease(lease_id)[source]

Retrieve lease metadata.

Supported methods:
PUT: /sys/leases/lookup. Produces: 200 application/json
Parameters:lease_id (str | unicode) – the ID of the lease to lookup.
Returns:Parsed JSON response from the leases PUT request
Return type:dict.
renew_lease(lease_id, increment=None)[source]

Renew a lease, requesting to extend the lease.

Supported methods:
PUT: /sys/leases/renew. Produces: 200 application/json
Parameters:
  • lease_id (str | unicode) – The ID of the lease to extend.
  • increment (int) – The requested amount of time (in seconds) to extend the lease.
Returns:

The JSON response of the request

Return type:

dict

revoke_force(prefix)[source]

Revoke all secrets or tokens generated under a given prefix immediately.

Unlike revoke_prefix, this path ignores backend errors encountered during revocation. This is potentially very dangerous and should only be used in specific emergency situations where errors in the backend or the connected backend service prevent normal revocation.

Supported methods:
PUT: /sys/leases/revoke-force/{prefix}. Produces: 204 (empty body)
Parameters:prefix (str | unicode) – The prefix to revoke.
Returns:The response of the request.
Return type:requests.Response
revoke_lease(lease_id)[source]

Revoke a lease immediately.

Supported methods:
PUT: /sys/leases/revoke. Produces: 204 (empty body)
Parameters:lease_id (str | unicode) – Specifies the ID of the lease to revoke.
Returns:The response of the request.
Return type:requests.Response
revoke_prefix(prefix)[source]

Revoke all secrets (via a lease ID prefix) or tokens (via the tokens’ path property) generated under a given prefix immediately.

This requires sudo capability and access to it should be tightly controlled as it can be used to revoke very large numbers of secrets/tokens at once.

Supported methods:
PUT: /sys/leases/revoke-prefix/{prefix}. Produces: 204 (empty body)
Parameters:prefix (str | unicode) – The prefix to revoke.
Returns:The response of the request.
Return type:requests.Response
class hvac.api.system_backend.Mount(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

disable_secrets_engine(path)[source]

Disable the mount point specified by the provided path.

Supported methods:
DELETE: /sys/mounts/{path}. Produces: 204 (empty body)
Parameters:path (str | unicode) – Specifies the path where the secrets engine will be mounted. This is specified as part of the URL.
Returns:The response of the request.
Return type:requests.Response
enable_secrets_engine(backend_type, path=None, description=None, config=None, plugin_name=None, options=None, local=False, seal_wrap=False, **kwargs)[source]

Enable a new secrets engine at the given path.

Supported methods:
POST: /sys/mounts/{path}. Produces: 204 (empty body)
Parameters:
  • backend_type (str | unicode) – The name of the backend type, such as “github” or “token”.
  • path (str | unicode) – The path to mount the method on. If not provided, defaults to the value of the “method_type” argument.
  • description (str | unicode) – A human-friendly description of the mount.
  • config (dict) –

    Configuration options for this mount. These are the possible values:

    • default_lease_ttl: The default lease duration, specified as a string duration like “5s” or “30m”.
    • max_lease_ttl: The maximum lease duration, specified as a string duration like “5s” or “30m”.
    • force_no_cache: Disable caching.
    • plugin_name: The name of the plugin in the plugin catalog to use.
    • audit_non_hmac_request_keys: Comma-separated list of keys that will not be HMAC’d by audit devices in the request data object.
    • audit_non_hmac_response_keys: Comma-separated list of keys that will not be HMAC’d by audit devices in the response data object.
    • listing_visibility: Specifies whether to show this mount in the UI-specific listing endpoint. (“unauth” or “hidden”)
    • passthrough_request_headers: Comma-separated list of headers to whitelist and pass from the request to the backend.
  • options (dict) –

    Specifies mount type specific options that are passed to the backend.

    • version: <KV> The version of the KV to mount. Set to “2” for mount KV v2.
  • plugin_name (str | unicode) – Specifies the name of the plugin to use based from the name in the plugin catalog. Applies only to plugin backends.
  • local (bool) – <Vault enterprise only> Specifies if the auth method is a local only. Local auth methods are not replicated nor (if a secondary) removed by replication.
  • seal_wrap (bool) – <Vault enterprise only> Enable seal wrapping for the mount.
  • kwargs (dict) – All dicts are accepted and passed to vault. See your specific secret engine for details on which extra key-word arguments you might want to pass.
Returns:

The response of the request.

Return type:

requests.Response

list_mounted_secrets_engines()[source]

Lists all the mounted secrets engines.

Supported methods:
POST: /sys/mounts. Produces: 200 application/json
Returns:JSON response of the request.
Return type:dict
move_backend(from_path, to_path)[source]

Move an already-mounted backend to a new mount point.

Supported methods:
POST: /sys/remount. Produces: 204 (empty body)
Parameters:
  • from_path (str | unicode) – Specifies the previous mount point.
  • to_path (str | unicode) – Specifies the new destination mount point.
Returns:

The response of the request.

Return type:

requests.Response

read_mount_configuration(path)[source]

Read the given mount’s configuration.

Unlike the mounts endpoint, this will return the current time in seconds for each TTL, which may be the system default or a mount-specific value.

Supported methods:
GET: /sys/mounts/{path}/tune. Produces: 200 application/json
Parameters:path (str | unicode) – Specifies the path where the secrets engine will be mounted. This is specified as part of the URL.
Returns:The JSON response of the request.
Return type:requests.Response
retrieve_mount_option(mount_point, option_name, default_value=None)[source]
tune_mount_configuration(path, default_lease_ttl=None, max_lease_ttl=None, description=None, audit_non_hmac_request_keys=None, audit_non_hmac_response_keys=None, listing_visibility=None, passthrough_request_headers=None, options=None, force_no_cache=None, **kwargs)[source]

Tune configuration parameters for a given mount point.

Supported methods:
POST: /sys/mounts/{path}/tune. Produces: 204 (empty body)
Parameters:
  • path (str | unicode) – Specifies the path where the secrets engine will be mounted. This is specified as part of the URL.
  • mount_point (str) – The path the associated secret backend is mounted
  • description (str) – Specifies the description of the mount. This overrides the current stored value, if any.
  • default_lease_ttl (int) – Default time-to-live. This overrides the global default. A value of 0 is equivalent to the system default TTL
  • max_lease_ttl (int) – Maximum time-to-live. This overrides the global default. A value of 0 are equivalent and set to the system max TTL.
  • audit_non_hmac_request_keys (list) – Specifies the comma-separated list of keys that will not be HMAC’d by audit devices in the request data object.
  • audit_non_hmac_response_keys (list) – Specifies the comma-separated list of keys that will not be HMAC’d by audit devices in the response data object.
  • listing_visibility (str) – Speficies whether to show this mount in the UI-specific listing endpoint. Valid values are “unauth” or “”.
  • passthrough_request_headers (str) – Comma-separated list of headers to whitelist and pass from the request to the backend.
  • options (dict) –

    Specifies mount type specific options that are passed to the backend.

    • version: <KV> The version of the KV to mount. Set to “2” for mount KV v2.
  • force_no_cache (bool) – Disable caching.
  • kwargs (dict) – All dicts are accepted and passed to vault. See your specific secret engine for details on which extra key-word arguments you might want to pass.
Returns:

The response from the request.

Return type:

request.Response

class hvac.api.system_backend.Namespace(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

create_namespace(path)[source]

Create a namespace at the given path.

Supported methods:
POST: /sys/namespaces/{path}. Produces: 200 application/json
Returns:The response of the request.
Return type:requests.Response
delete_namespace(path)[source]

Delete a namespaces. You cannot delete a namespace with existing child namespaces.

Supported methods:
DELETE: /sys/namespaces. Produces: 204 (empty body)
Returns:The response of the request.
Return type:requests.Response
list_namespaces()[source]

Lists all the namespaces.

Supported methods:
LIST: /sys/namespaces. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
class hvac.api.system_backend.Policy(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

create_or_update_policy(name, policy, pretty_print=True)[source]

Add a new or update an existing policy.

Once a policy is updated, it takes effect immediately to all associated users.

Supported methods:
PUT: /sys/policy/{name}. Produces: 204 (empty body)
Parameters:
  • name (str | unicode) – Specifies the name of the policy to create.
  • policy (str | unicode | dict) – Specifies the policy document.
  • pretty_print (bool) – If True, and provided a dict for the policy argument, send the policy JSON to Vault with “pretty” formatting.
Returns:

The response of the request.

Return type:

requests.Response

delete_policy(name)[source]

Delete the policy with the given name.

This will immediately affect all users associated with this policy.

Supported methods:
DELETE: /sys/policy/{name}. Produces: 204 (empty body)
Parameters:name (str | unicode) – Specifies the name of the policy to delete.
Returns:The response of the request.
Return type:requests.Response
list_policies()[source]

List all configured policies.

Supported methods:
GET: /sys/policy. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
read_policy(name)[source]

Retrieve the policy body for the named policy.

Supported methods:
GET: /sys/policy/{name}. Produces: 200 application/json
Parameters:name (str | unicode) – The name of the policy to retrieve.
Returns:The response of the request
Return type:dict
class hvac.api.system_backend.Seal(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

is_sealed()[source]

Determine if Vault is sealed.

Returns:True if Vault is seal, False otherwise.
Return type:bool
read_seal_status()[source]

Read the seal status of the Vault.

This is an unauthenticated endpoint.

Supported methods:
GET: /sys/seal-status. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict
seal()[source]

Seal the Vault.

In HA mode, only an active node can be sealed. Standby nodes should be restarted to get the same effect. Requires a token with root policy or sudo capability on the path.

Supported methods:
PUT: /sys/seal. Produces: 204 (empty body)
Returns:The response of the request.
Return type:requests.Response
submit_unseal_key(key=None, reset=False, migrate=False)[source]

Enter a single master key share to progress the unsealing of the Vault.

If the threshold number of master key shares is reached, Vault will attempt to unseal the Vault. Otherwise, this API must be called multiple times until that threshold is met.

Either the key or reset parameter must be provided; if both are provided, reset takes precedence.

Supported methods:
PUT: /sys/unseal. Produces: 200 application/json
Parameters:
  • key (str | unicode) – Specifies a single master key share. This is required unless reset is true.
  • reset (bool) – Specifies if previously-provided unseal keys are discarded and the unseal process is reset.
  • migrate – Available in 1.0 Beta - Used to migrate the seal from shamir to autoseal or autoseal to shamir. Must be provided on all unseal key calls.
Type:

migrate: bool

Returns:

The JSON response of the request.

Return type:

dict

submit_unseal_keys(keys, migrate=False)[source]

Enter multiple master key share to progress the unsealing of the Vault.

Parameters:
  • keys (List[str]) – List of master key shares.
  • migrate – Available in 1.0 Beta - Used to migrate the seal from shamir to autoseal or autoseal to shamir. Must be provided on all unseal key calls.
Type:

migrate: bool

Returns:

The JSON response of the last unseal request.

Return type:

dict

class hvac.api.system_backend.SystemBackend(adapter)[source]

Bases: hvac.api.vault_api_category.VaultApiCategory, hvac.api.system_backend.audit.Audit, hvac.api.system_backend.auth.Auth, hvac.api.system_backend.capabilities.Capabilities, hvac.api.system_backend.health.Health, hvac.api.system_backend.init.Init, hvac.api.system_backend.key.Key, hvac.api.system_backend.leader.Leader, hvac.api.system_backend.lease.Lease, hvac.api.system_backend.mount.Mount, hvac.api.system_backend.namespace.Namespace, hvac.api.system_backend.policy.Policy, hvac.api.system_backend.seal.Seal, hvac.api.system_backend.wrapping.Wrapping

__init__(adapter)[source]

API Category class constructor.

Parameters:adapter (hvac.adapters.Adapter) – Instance of hvac.adapters.Adapter; used for performing HTTP requests.
implemented_classes = [<class 'hvac.api.system_backend.audit.Audit'>, <class 'hvac.api.system_backend.auth.Auth'>, <class 'hvac.api.system_backend.capabilities.Capabilities'>, <class 'hvac.api.system_backend.health.Health'>, <class 'hvac.api.system_backend.init.Init'>, <class 'hvac.api.system_backend.key.Key'>, <class 'hvac.api.system_backend.leader.Leader'>, <class 'hvac.api.system_backend.lease.Lease'>, <class 'hvac.api.system_backend.mount.Mount'>, <class 'hvac.api.system_backend.namespace.Namespace'>, <class 'hvac.api.system_backend.policy.Policy'>, <class 'hvac.api.system_backend.seal.Seal'>, <class 'hvac.api.system_backend.wrapping.Wrapping'>]
unimplemented_classes = []
class hvac.api.system_backend.SystemBackendMixin(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Base class for System Backend API endpoints.

class hvac.api.system_backend.Wrapping(adapter)[source]

Bases: hvac.api.system_backend.system_backend_mixin.SystemBackendMixin

unwrap(token=None)[source]

Return the original response inside the given wrapping token.

Unlike simply reading cubbyhole/response (which is deprecated), this endpoint provides additional validation checks on the token, returns the original value on the wire rather than a JSON string representation of it, and ensures that the response is properly audit-logged.

Supported methods:
POST: /sys/wrapping/unwrap. Produces: 200 application/json
Parameters:token (str | unicode) – Specifies the wrapping token ID. This is required if the client token is not the wrapping token. Do not use the wrapping token in both locations.
Returns:The JSON response of the request.
Return type:dict