hvac.api.system_backend

Collection of Vault system backend API endpoint classes.

Classes:

`Audit`(adapter)
`Auth`(adapter)
`Capabilities`(adapter)
`Health`(adapter)	.
`Init`(adapter)
`Key`(adapter)
`Leader`(adapter)
`Lease`(adapter)
`Mount`(adapter)
`Namespace`(adapter)
`Policies`(adapter)
`Policy`(adapter)
`Quota`(adapter)
`Raft`(adapter)	Raft cluster-related system backend methods.
`Seal`(adapter)
`SystemBackend`(adapter)
`SystemBackendMixin`(adapter)	Base class for System Backend API endpoints.
`Wrapping`(adapter)

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

Bases: SystemBackendMixin

Methods:

`calculate_hash`(path, input_to_hash)	Hash the given input data with the specified audit device's hash function and salt.
`disable_audit_device`(path)	Disable the audit device at the given path.
`enable_audit_device`(device_type[, ...])	Enable a new audit device at the supplied path.
`list_enabled_audit_devices`()	List enabled audit devices.

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, local=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.
local (bool) – Specifies if the audit device is a local only.

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: SystemBackendMixin

Methods:

`disable_auth_method`(path)	Disable the auth method at the given auth path.
`enable_auth_method`(method_type[, ...])	Enable a new auth method.
`list_auth_methods`()	List all enabled auth methods.
`read_auth_method_tuning`(path)	Read the given auth path's configuration.
`tune_auth_method`(path[, default_lease_ttl, ...])	Tune configuration parameters for a given auth path.

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: Specifies 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=None, 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: SystemBackendMixin

Methods:

get_capabilities(paths[, token, accessor])

Get the capabilities associated with a token.

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: SystemBackendMixin

.

Reference: https://www.vaultproject.io/api-docs/system/health

Methods:

read_health_status([standby_ok, ...])

Read the health status of Vault.

read_health_status(standby_ok=None, active_code=None, standby_code=None, dr_secondary_code=None, performance_standby_code=None, sealed_code=None, uninit_code=None, 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: SystemBackendMixin

Methods:

`initialize`([secret_shares, ...])	Initialize a new Vault.
`is_initialized`()	Determine is Vault is initialized or not.
`read_init_status`()	Read the initialization status of Vault.

initialize(secret_shares=None, secret_threshold=None, 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, or omitted, depending on the version of Vault and the seal type.
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: SystemBackendMixin

Methods:

`cancel_rekey`([recovery_key])	Cancel any in-progress rekey.
`cancel_rekey_verify`()	Cancel any in-progress rekey verification.
`cancel_root_generation`()	Cancel any in-progress root generation attempt.
`generate_root`(key, nonce)	Enter a single master key share to progress the root generation attempt.
`get_encryption_key_status`()	Read information about the current encryption key used by Vault.
`read_backup_keys`([recovery_key])	Retrieve the backup copy of PGP-encrypted unseal keys.
`read_rekey_progress`([recovery_key])	Read the configuration and progress of the current rekey attempt.
`read_rekey_verify_progress`()	Read the configuration and progress of the current rekey verify attempt.
`read_root_generation_progress`()	Read the configuration and process of the current root generation attempt.
`rekey`(key[, nonce, recovery_key])	Enter a single recovery key share to progress the rekey of the Vault.
`rekey_multi`(keys[, nonce, recovery_key])	Enter multiple recovery key shares to progress the rekey of the Vault.
`rekey_verify`(key, nonce)	Enter a single new recovery key share to progress the rekey verification of the Vault.
`rekey_verify_multi`(keys, nonce)	Enter multiple new recovery key shares to progress the rekey verification of the Vault.
`rotate_encryption_key`()	Trigger a rotation of the backend encryption key.
`start_rekey`([secret_shares, ...])	Initializes a new rekey attempt.
`start_root_token_generation`([otp, pgp_key])	Initialize a new root generation attempt.

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_rekey_verify()[source]

Cancel any in-progress rekey verification. This clears any progress made and resets the nonce. Unlike cancel_rekey, this only resets the current verification operation, not the entire rekey atttempt. The return value is the same as GET along with the new nonce.

Supported methods:: DELETE: /sys/rekey/verify. Produces: 204 (empty body)

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_rekey_verify_progress()[source]

Read the configuration and progress of the current rekey verify attempt.

Supported methods:: GET: /sys/rekey/verify. Produces: 200 application/json

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

rekey_verify(key, nonce)[source]

Enter a single new recovery key share to progress the rekey verification of the Vault. If the threshold number of new 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 verification nonce must be provided with each call.

Supported methods:: PUT: /sys/rekey/verify. Produces: 200 application/json

Parameters:

key (str | unicode) – Specifies multiple recovery share keys.
nonce (str | unicode) – Specifies the nonce of the rekey verify operation.

Returns:

The JSON response of the request.

Return type:

dict

rekey_verify_multi(keys, nonce)[source]

Enter multiple new recovery key shares to progress the rekey verification of the Vault. If the threshold number of new 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 verification nonce must be provided with each call.

Supported methods:: PUT: /sys/rekey/verify. Produces: 200 application/json

Parameters:

keys (list) – Specifies multiple recovery share keys.
nonce (str | unicode) – Specifies the nonce of the rekey verify operation.

Returns:

The JSON response of the request.

Return type:

dict

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: SystemBackendMixin

Methods:

`read_leader_status`()	Read the high availability status and current leader instance of Vault.
`step_down`()	Force the node to give up active status.

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

step_down()[source]

Force the node to give up active status.

When executed against a non-active node, i.e. a standby or performance standby node, the request will be forwarded to the active node. Note that the node will sleep for ten seconds before attempting to grab the active lock again, but if no standby nodes grab the active lock in the interim, the same node may become the active node again. Requires a token with root policy or sudo capability on the path.

Returns:: The JSON response of the request.
Return type:: dict

class hvac.api.system_backend.Lease(adapter)[source]

Bases: SystemBackendMixin

Methods:

`list_leases`(prefix)	Retrieve a list of lease ids.
`read_lease`(lease_id)	Retrieve lease metadata.
`renew_lease`(lease_id[, increment])	Renew a lease, requesting to extend the lease.
`revoke_force`(prefix)	Revoke all secrets or tokens generated under a given prefix immediately.
`revoke_lease`(lease_id)	Revoke a lease immediately.
`revoke_prefix`(prefix)	Revoke all secrets (via a lease ID prefix) or tokens (via the tokens' path property) generated under a given prefix immediately.

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: SystemBackendMixin

Methods:

`disable_secrets_engine`(path)	Disable the mount point specified by the provided path.
`enable_secrets_engine`(backend_type[, path, ...])	Enable a new secrets engine at the given path.
`list_mounted_secrets_engines`()	Lists all the mounted secrets engines.
`move_backend`(from_path, to_path)	Move an already-mounted backend to a new mount point.
`read_mount_configuration`(path)	Read the given mount's configuration.
`retrieve_mount_option`(mount_point, option_name)
`tune_mount_configuration`(path[, ...])	Tune configuration parameters for a given mount point.

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 “backend_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) – Specifies 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: SystemBackendMixin

Methods:

`create_namespace`(path)	Create a namespace at the given path.
`delete_namespace`(path)	Delete a namespaces.
`list_namespaces`()	Lists all the namespaces.

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.Policies(adapter)[source]

Bases: SystemBackendMixin

Methods:

`create_or_update_acl_policy`(name, policy[, ...])	Add a new or update an existing acl policy.
`create_or_update_egp_policy`(name, policy, ...)	Add a new or update an existing egp policy.
`create_or_update_rgp_policy`(name, policy, ...)	Add a new or update an existing rgp policy.
`delete_acl_policy`(name)	Delete the acl policy with the given name.
`delete_egp_policy`(name)	Delete the egp policy with the given name.
`delete_rgp_policy`(name)	Delete the rgp policy with the given name.
`list_acl_policies`()	List all configured acl policies.
`list_egp_policies`()	List all configured egp policies.
`list_rgp_policies`()	List all configured rgp policies.
`read_acl_policy`(name)	Retrieve the policy body for the named acl policy.
`read_egp_policy`(name)	Retrieve the policy body for the named egp policy.
`read_rgp_policy`(name)	Retrieve the policy body for the named rgp policy.

create_or_update_acl_policy(name, policy, pretty_print=True)[source]

Add a new or update an existing acl policy.

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

Supported methods:: PUT: /sys/policies/acl/{name}. Produces: 204 (empty body)

Parameters:

name (str | unicode) – Specifies the name of the policy to create.
policy (str | unicode | dict) – Specifies the policy to create or update.
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

create_or_update_egp_policy(name, policy, enforcement_level, paths)[source]

Add a new or update an existing egp policy.

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

Supported methods:: PUT: /sys/policies/egp/{name}. Produces: 204 (empty body)

Parameters:

name (str | unicode) – Specifies the name of the policy to create.
policy (str | unicode) – Specifies the policy to create or update.
enforcement_level (str | unicode) – Specifies the enforcement level to use. This must be one of advisory, soft-mandatory, or hard-mandatory
paths (list) – Specifies the paths on which this EGP should be applied.

Returns:

The response of the request.

Return type:

requests.Response

create_or_update_rgp_policy(name, policy, enforcement_level)[source]

Add a new or update an existing rgp policy.

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

Supported methods:: PUT: /sys/policies/rgp/{name}. Produces: 204 (empty body)

Parameters:

name (str | unicode) – Specifies the name of the policy to create.
policy (str | unicode) – Specifies the policy to create or update.
enforcement_level (str | unicode) – Specifies the enforcement level to use. This must be one of advisory, soft-mandatory, or hard-mandatory

Returns:

The response of the request.

Return type:

requests.Response

delete_acl_policy(name)[source]

Delete the acl policy with the given name.

This will immediately affect all users associated with this policy.

Supported methods:: DELETE: /sys/policies/acl/{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

delete_egp_policy(name)[source]

Delete the egp policy with the given name.

This will immediately affect all users associated with this policy.

Supported methods:: DELETE: /sys/policies/egp/{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

delete_rgp_policy(name)[source]

Delete the rgp policy with the given name.

This will immediately affect all users associated with this policy.

Supported methods:: DELETE: /sys/policies/rgp/{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_acl_policies()[source]

List all configured acl policies.

Supported methods:: GET: /sys/policies/acl. Produces: 200 application/json

Returns:: The JSON response of the request.
Return type:: dict

list_egp_policies()[source]

List all configured egp policies.

Supported methods:: GET: /sys/policies/egp. Produces: 200 application/json

Returns:: The JSON response of the request.
Return type:: dict

list_rgp_policies()[source]

List all configured rgp policies.

Supported methods:: GET: /sys/policies/rgp. Produces: 200 application/json

Returns:: The JSON response of the request.
Return type:: dict

read_acl_policy(name)[source]

Retrieve the policy body for the named acl policy.

Supported methods:: GET: /sys/policies/acl/{name}. Produces: 200 application/json

Parameters:: name (str | unicode) – The name of the acl policy to retrieve.
Returns:: The response of the request
Return type:: dict

read_egp_policy(name)[source]

Retrieve the policy body for the named egp policy.

Supported methods:: GET: /sys/policies/egp/{name}. Produces: 200 application/json

Parameters:: name (str | unicode) – The name of the egp policy to retrieve.
Returns:: The response of the request
Return type:: dict

read_rgp_policy(name)[source]

Retrieve the policy body for the named rgp policy.

Supported methods:: GET: /sys/policies/rgp/{name}. Produces: 200 application/json

Parameters:: name (str | unicode) – The name of the rgp policy to retrieve.
Returns:: The response of the request
Return type:: dict

class hvac.api.system_backend.Policy(adapter)[source]

Bases: SystemBackendMixin

Methods:

`create_or_update_policy`(name, policy[, ...])	Add a new or update an existing policy.
`delete_policy`(name)	Delete the policy with the given name.
`list_policies`()	List all configured policies.
`read_policy`(name)	Retrieve the policy body for the named policy.

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.Quota(adapter)[source]

Bases: SystemBackendMixin

Methods:

`create_or_update_quota`(name, rate[, path, ...])	Create quota if it doesn't exist or update if already created.
`delete_quota`(name)	Delete a given quota.
`list_quotas`()	Retrieve a list of quotas by name.
`read_quota`(name)	Read quota.

create_or_update_quota(name, rate, path=None, interval=None, block_interval=None, role=None, rate_limit_type=None, inheritable=None)[source]

Create quota if it doesn’t exist or update if already created. Only works when calling on the root namespace.

Supported methods:: POST: /sys/quotas/rate-limit. Produces: 204 (empty body)

Parameters:

name (str | unicode) – The name of the quota to create or update.
path (str | unicode) – Path of the mount or namespace to apply the quota.
rate (float) – The maximum number of requests in a given interval to be allowed. Must be positive.
interval (str | unicode) – The duration to enforce rate limit. Default is “1s”.
block_interval (str | unicode) – If rate limit is reached, how long before client can send requests again.
role (str | unicode) – If quota is set on an auth mount path, restrict login requests that are made with a specified role.
rate_limit_type (str | unicode) – Type of rate limit quota. Can be lease-count or rate-limit.
inheritable (bool) – If set to true on a path that is a namespace, quota will be applied to all child namespaces

Returns:

API status code from request.

Return type:

requests.Response

delete_quota(name)[source]

Delete a given quota. Only works when calling on the root namespace.

Supported methods:: DELETE: /sys/quotas/rate-limit. Produces: 204 (empty body)

Parameters:: name (str | unicode) – Name of the quota to delete
Returns:: API status code from request.
Return type:: requests.Response

list_quotas()[source]

Retrieve a list of quotas by name. Only works when calling on the root namespace.

Supported methods:: LIST: /sys/quotas/rate-limit. Produces: 200 application/json

Returns:: JSON response from API request.
Return type:: requests.Response

read_quota(name)[source]

Read quota. Only works when calling on the root namespace.

Supported methods:: GET: /sys/quotas/rate-limit/:name. Produces: 200 application/json

Parameters:: name (str | unicode) – the name of the quota to look up.
Returns:: JSON response from API request.
Return type:: requests.Response

class hvac.api.system_backend.Raft(adapter)[source]

Bases: SystemBackendMixin

Raft cluster-related system backend methods.

When using Shamir seal, as soon as the Vault server is brought up, this API should be invoked instead of sys/init. This API completes in 2 phases. Once this is invoked, the joining node will receive a challenge from the Raft’s leader node. This challenge can be answered by the joining node only after a successful unseal. Hence, the joining node should be unsealed using the unseal keys of the Raft’s leader node.

Reference: https://www.vaultproject.io/api-docs/system/storage/raft

Methods:

`force_restore_raft_snapshot`(snapshot)	Installs the provided snapshot, returning the cluster to the state defined in it.
`join_raft_cluster`(leader_api_addr[, retry, ...])	Join a new server node to the Raft cluster.
`read_raft_config`()	Read the details of all the nodes in the raft cluster.
`remove_raft_node`(server_id)	Remove a node from the raft cluster.
`restore_raft_snapshot`(snapshot)	Install the provided snapshot, returning the cluster to the state defined in it.
`take_raft_snapshot`()	Returns a snapshot of the current state of the raft cluster.

force_restore_raft_snapshot(snapshot)[source]

Installs the provided snapshot, returning the cluster to the state defined in it.

This is same as writing to /sys/storage/raft/snapshot except that this bypasses checks ensuring the Autounseal or shamir keys are consistent with the snapshot data.

Supported methods:: POST: /sys/storage/raft/snapshot-force.

Parameters:: snapshot (bytes) – Previously created raft snapshot / binary data.
Returns:: The response of the force_restore_raft_snapshot request.
Return type:: requests.Response

join_raft_cluster(leader_api_addr, retry=False, leader_ca_cert=None, leader_client_cert=None, leader_client_key=None)[source]

Join a new server node to the Raft cluster.

When using Shamir seal, as soon as the Vault server is brought up, this API should be invoked instead of sys/init. This API completes in 2 phases. Once this is invoked, the joining node will receive a challenge from the Raft’s leader node. This challenge can be answered by the joining node only after a successful unseal. Hence, the joining node should be unsealed using the unseal keys of the Raft’s leader node.

Supported methods:: POST: /sys/storage/raft/join.

Parameters:

leader_api_addr (str | unicode) – Address of the leader node in the Raft cluster to which this node is trying to join.
retry (bool) – Retry joining the Raft cluster in case of failures.
leader_ca_cert (str | unicode) – CA certificate used to communicate with Raft’s leader node.
leader_client_cert (str | unicode) – Client certificate used to communicate with Raft’s leader node.
leader_client_key (str | unicode) – Client key used to communicate with Raft’s leader node.

Returns:

The response of the join_raft_cluster request.

Return type:

requests.Response

read_raft_config()[source]

Read the details of all the nodes in the raft cluster.

Supported methods:: GET: /sys/storage/raft/configuration.

Returns:: The response of the read_raft_config request.
Return type:: requests.Response

remove_raft_node(server_id)[source]

Remove a node from the raft cluster.

Supported methods:: POST: /sys/storage/raft/remove-peer.

Parameters:: server_id (str) – The ID of the node to remove.
Returns:: The response of the remove_raft_node request.
Return type:: requests.Response

restore_raft_snapshot(snapshot)[source]

Install the provided snapshot, returning the cluster to the state defined in it.

Supported methods:: POST: /sys/storage/raft/snapshot.

Parameters:: snapshot (bytes) – Previously created raft snapshot / binary data.
Returns:: The response of the restore_raft_snapshot request.
Return type:: requests.Response

take_raft_snapshot()[source]

Returns a snapshot of the current state of the raft cluster.

The snapshot is returned as binary data and should be redirected to a file.

This endpoint will ignore your chosen adapter and always uses a RawAdapter.

Supported methods:: GET: /sys/storage/raft/snapshot.

Returns:: The response of the snapshot request.
Return type:: requests.Response

class hvac.api.system_backend.Seal(adapter)[source]

Bases: SystemBackendMixin

Methods:

`is_sealed`()	Determine if Vault is sealed.
`read_seal_status`()	Read the seal status of the Vault.
`seal`()	Seal the Vault.
`submit_unseal_key`([key, reset, migrate])	Enter a single master key share to progress the unsealing of the Vault.
`submit_unseal_keys`(keys[, migrate])	Enter multiple master key share to progress the unsealing of the Vault.

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: VaultApiCategory, Audit, Auth, Capabilities, Health, Init, Key, Leader, Lease, Mount, Namespace, Policies, Policy, Quota, Raft, Seal, Wrapping

Attributes:

`implemented_classes`
`unimplemented_classes`

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.policies.Policies'>, <class 'hvac.api.system_backend.policy.Policy'>, <class 'hvac.api.system_backend.quota.Quota'>, <class 'hvac.api.system_backend.raft.Raft'>, <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: VaultApiBase

Base class for System Backend API endpoints.

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

Bases: SystemBackendMixin

Methods:

unwrap([token])

Return the original response inside the given wrapping token.

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