hvac.api.secrets_engines

Vault secrets engines endpoints

Classes

Aws(adapter)

AWS Secrets Engine (API).

Azure(adapter)

Azure Secrets Engine (API).

Gcp(adapter)

Google Cloud Secrets Engine (API).

ActiveDirectory(adapter)

Active Directory Secrets Engine (API).

Identity(adapter)

Identity Secrets Engine (API).

Kv(adapter[, default_kv_version])

Class containing methods for the key/value secrets_engines backend API routes.

KvV1(adapter)

KV Secrets Engine - Version 1 (API).

KvV2(adapter)

KV Secrets Engine - Version 2 (API).

Pki(adapter)

Pki Secrets Engine (API).

Transform(adapter)

Transform Secrets Engine (API).

Transit(adapter)

Transit Secrets Engine (API).

SecretsEngines(adapter)

Secrets Engines.

Database(adapter)

Database Secrets Engine (API).

RabbitMQ(adapter)

RabbitMQ Secrets Engine (API).

class hvac.api.secrets_engines.ActiveDirectory(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Active Directory Secrets Engine (API). Reference: https://www.vaultproject.io/api/secret/ad/index.html

Methods

configure([binddn, bindpass, url, userdn, …])

Configure shared information for the ad secrets engine.

create_or_update_role(name[, …])

This endpoint creates or updates the ad role definition.

delete_role(name[, mount_point])

This endpoint deletes a ad role with the given name.

list_roles([mount_point])

This endpoint lists all existing roles in the secrets engine.

read_config([mount_point])

Read the configured shared information for the ad secrets engine.

read_role(name[, mount_point])

This endpoint queries for information about a ad role with the given name.

configure(binddn=None, bindpass=None, url=None, userdn=None, upndomain=None, ttl=None, max_ttl=None, mount_point='ad', *args, **kwargs)[source]

Configure shared information for the ad secrets engine.

Supported methods:

POST: /{mount_point}/config. Produces: 204 (empty body)

Parameters
  • binddn (str | unicode) – Distinguished name of object to bind when performing user and group search.

  • bindpass (str | unicode) – Password to use along with binddn when performing user search.

  • url (str | unicode) – Base DN under which to perform user search.

  • userdn (str | unicode) – Base DN under which to perform user search.

  • upndomain (str | unicode) – userPrincipalDomain used to construct the UPN string for the authenticating user.

  • ttl (int | str) – – The default password time-to-live in seconds. Once the ttl has passed, a password will be rotated the next time it’s requested.

  • max_ttl (int | str) – The maximum password time-to-live in seconds. No role will be allowed to set a custom ttl greater than the max_ttl integer number of seconds or Go duration format string.**

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_or_update_role(name, service_account_name=None, ttl=None, mount_point='ad')[source]

This endpoint creates or updates the ad role definition.

Parameters
  • name (str | unicode) – Specifies the name of an existing role against which to create this ad credential.

  • service_account_name (str | unicode) – The name of a pre-existing service account in Active Directory that maps to this role. This value is required on create and optional on update.

  • ttl (str | unicode) – Specifies the TTL for this role. This is provided as a string duration with a time suffix like “30s” or “1h” or as seconds. If not provided, the default Vault TTL is used.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: ad).

Returns

The response of the request.

Return type

requests.Response

delete_role(name, mount_point='ad')[source]

This endpoint deletes a ad role with the given name. Even if the role does not exist, this endpoint will still return a successful response. :param name: Specifies the name of the role to delete. :type name: str | unicode :param mount_point: Specifies the place where the secrets engine will be accessible (default: ad). :type mount_point: str | unicode :return: The response of the request. :rtype: requests.Response

list_roles(mount_point='ad')[source]

This endpoint lists all existing roles in the secrets engine. :return: The response of the request. :rtype: requests.Response

read_config(mount_point='ad')[source]

Read the configured shared information for the ad secrets engine.

Credentials will be omitted from returned data.

Supported methods:

GET: /{mount_point}/config. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_role(name, mount_point='ad')[source]

This endpoint queries for information about a ad role with the given name. If no role exists with that name, a 404 is returned. :param name: Specifies the name of the role to query. :type name: str | unicode :param mount_point: Specifies the place where the secrets engine will be accessible (default: ad). :type mount_point: str | unicode :return: The response of the request. :rtype: requests.Response

class hvac.api.secrets_engines.Aws(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

AWS Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/aws/index.html

Methods

configure_lease(lease, lease_max[, mount_point])

Configure lease settings for the AWS secrets engine.

configure_root_iam_credentials(access_key, …)

Configure the root IAM credentials to communicate with AWS.

create_or_update_role(name, credential_type)

Create or update the role with the given name.

delete_role(name[, mount_point])

Delete an existing role by the given name.

generate_credentials(name[, role_arn, ttl, …])

Generates credential based on the named role.

list_roles([mount_point])

List all existing roles in the secrets engine.

read_lease_config([mount_point])

Read the current lease settings for the AWS secrets engine.

read_role(name[, mount_point])

Query an existing role by the given name.

rotate_root_iam_credentials([mount_point])

Rotate static root IAM credentials.

configure_lease(lease, lease_max, mount_point='aws')[source]

Configure lease settings for the AWS secrets engine.

It is optional, as there are default values for lease and lease_max.

Supported methods:

POST: /{mount_point}/config/lease. Produces: 204 (empty body)

Parameters
  • lease (str | unicode) – Specifies the lease value provided as a string duration with time suffix. “h” (hour) is the largest suffix.

  • lease_max (str | unicode) – Specifies the maximum lease value provided as a string duration with time suffix. “h” (hour) is the largest suffix.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

configure_root_iam_credentials(access_key, secret_key, region=None, iam_endpoint=None, sts_endpoint=None, max_retries=None, mount_point='aws')[source]

Configure the root IAM credentials to communicate with AWS.

There are multiple ways to pass root IAM credentials to the Vault server, specified below with the highest precedence first. If credentials already exist, this will overwrite them.

The official AWS SDK is used for sourcing credentials from env vars, shared files, or IAM/ECS instances.

  • Static credentials provided to the API as a payload

  • Credentials in the AWS_ACCESS_KEY, AWS_SECRET_KEY, and AWS_REGION environment variables on the server

  • Shared credentials files

  • Assigned IAM role or ECS task role credentials

At present, this endpoint does not confirm that the provided AWS credentials are valid AWS credentials with proper permissions.

Supported methods:

POST: /{mount_point}/config/root. Produces: 204 (empty body)

Parameters
  • access_key (str | unicode) – Specifies the AWS access key ID.

  • secret_key (str | unicode) – Specifies the AWS secret access key.

  • region (str | unicode) – Specifies the AWS region. If not set it will use the AWS_REGION env var, AWS_DEFAULT_REGION env var, or us-east-1 in that order.

  • iam_endpoint (str | unicode) – Specifies a custom HTTP IAM endpoint to use.

  • sts_endpoint (str | unicode) – Specifies a custom HTTP STS endpoint to use.

  • max_retries (int) – Number of max retries the client should use for recoverable errors. The default (-1) falls back to the AWS SDK’s default behavior.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_or_update_role(name, credential_type, policy_document=None, default_sts_ttl=None, max_sts_ttl=None, role_arns=None, policy_arns=None, legacy_params=False, mount_point='aws')[source]

Create or update the role with the given name.

If a role with the name does not exist, it will be created. If the role exists, it will be updated with the new attributes.

Supported methods:

POST: /{mount_point}/roles/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Specifies the name of the role to create. This is part of the request URL.

  • credential_type (str | unicode) – Specifies the type of credential to be used when retrieving credentials from the role. Must be one of iam_user, assumed_role, or federation_token.

  • policy_document (dict | str | unicode) – The IAM policy document for the role. The behavior depends on the credential type. With iam_user, the policy document will be attached to the IAM user generated and augment the permissions the IAM user has. With assumed_role and federation_token, the policy document will act as a filter on what the credentials can do.

  • default_sts_ttl (str | unicode) – The default TTL for STS credentials. When a TTL is not specified when STS credentials are requested, and a default TTL is specified on the role, then this default TTL will be used. Valid only when credential_type is one of assumed_role or federation_token.

  • max_sts_ttl (str | unicode) – The max allowed TTL for STS credentials (credentials TTL are capped to max_sts_ttl). Valid only when credential_type is one of assumed_role or federation_token.

  • role_arns (list | str | unicode) – Specifies the ARNs of the AWS roles this Vault role is allowed to assume. Required when credential_type is assumed_role and prohibited otherwise. This is a comma-separated string or JSON array. String types supported for Vault legacy parameters.

  • policy_arns (list) – Specifies the ARNs of the AWS managed policies to be attached to IAM users when they are requested. Valid only when credential_type is iam_user. When credential_type is iam_user, at least one of policy_arns or policy_document must be specified. This is a comma-separated string or JSON array.

  • legacy_params (bool) – Flag to send legacy (Vault versions < 0.11.0) parameters in the request. When this is set to True, policy_document and policy_arns are the only parameters used from this method.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_role(name, mount_point='aws')[source]

Delete an existing role by the given name.

If the role does not exist, a 404 is returned.

Supported methods:

DELETE: /{mount_point}/roles/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – the name of the role to delete. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

generate_credentials(name, role_arn=None, ttl=None, endpoint='creds', mount_point='aws')[source]

Generates credential based on the named role.

This role must be created before queried.

The /aws/creds and /aws/sts endpoints are almost identical. The exception is when retrieving credentials for a role that was specified with the legacy arn or policy parameter. In this case, credentials retrieved through /aws/sts must be of either the assumed_role or federation_token types, and credentials retrieved through /aws/creds must be of the iam_user type.

Parameters
  • name (str | unicode) – Specifies the name of the role to generate credentials against. This is part of the request URL.

  • role_arn (str | unicode) – The ARN of the role to assume if credential_type on the Vault role is assumed_role. Must match one of the allowed role ARNs in the Vault role. Optional if the Vault role only allows a single AWS role ARN; required otherwise.

  • ttl (str | unicode) – Specifies the TTL for the use of the STS token. This is specified as a string with a duration suffix. Valid only when credential_type is assumed_role or federation_token. When not specified, the default sts_ttl set for the role will be used. If that is also not set, then the default value of 3600s will be used. AWS places limits on the maximum TTL allowed. See the AWS documentation on the DurationSeconds parameter for AssumeRole (for assumed_role credential types) and GetFederationToken (for federation_token credential types) for more details.

  • endpoint (str | unicode) – Supported endpoints: GET: /{mount_point}/creds/{name}. Produces: 200 application/json GET: /{mount_point}/sts/{name}. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_roles(mount_point='aws')[source]

List all existing roles in the secrets engine.

Supported methods:

LIST: /{mount_point}/roles. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_lease_config(mount_point='aws')[source]

Read the current lease settings for the AWS secrets engine.

Supported methods:

GET: /{mount_point}/config/lease. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_role(name, mount_point='aws')[source]

Query an existing role by the given name.

If the role does not exist, a 404 is returned.

Supported methods:

GET: /{mount_point}/roles/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the role to read. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

rotate_root_iam_credentials(mount_point='aws')[source]

Rotate static root IAM credentials.

When you have configured Vault with static credentials, you can use this endpoint to have Vault rotate the access key it used. Note that, due to AWS eventual consistency, after calling this endpoint, subsequent calls from Vault to AWS may fail for a few seconds until AWS becomes consistent again.

In order to call this endpoint, Vault’s AWS access key MUST be the only access key on the IAM user; otherwise, generation of a new access key will fail. Once this method is called, Vault will now be the only entity that knows the AWS secret key is used to access AWS.

Supported methods:

POST: /{mount_point}/config/rotate-root. Produces: 200 application/json

Returns

The JSON response of the request.

Return type

dict

class hvac.api.secrets_engines.Azure(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Azure Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/azure/index.html

Methods

configure(subscription_id, tenant_id[, …])

Configure the credentials required for the plugin to perform API calls to Azure.

create_or_update_role(name, azure_roles[, …])

Create or update a Vault role.

delete_config([mount_point])

Delete the stored Azure configuration and credentials.

generate_credentials(name[, mount_point])

Generate a new service principal based on the named role.

list_roles([mount_point])

List all of the roles that are registered with the plugin.

read_config([mount_point])

Read the stored configuration, omitting client_secret.

configure(subscription_id, tenant_id, client_id=None, client_secret=None, environment=None, mount_point='azure')[source]

Configure the credentials required for the plugin to perform API calls to Azure.

These credentials will be used to query roles and create/delete service principals. Environment variables will override any parameters set in the config.

Supported methods:

POST: /{mount_point}/config. Produces: 204 (empty body)

Parameters
  • subscription_id (str | unicode) – The subscription id for the Azure Active Directory

  • tenant_id (str | unicode) – The tenant id for the Azure Active Directory.

  • client_id (str | unicode) – The OAuth2 client id to connect to Azure.

  • client_secret (str | unicode) – The OAuth2 client secret to connect to Azure.

  • environment (str | unicode) – The Azure environment. If not specified, Vault will use Azure Public Cloud.

  • mount_point (str | unicode) – The OAuth2 client secret to connect to Azure.

Returns

The response of the request.

Return type

requests.Response

create_or_update_role(name, azure_roles, ttl=None, max_ttl=None, mount_point='azure')[source]

Create or update a Vault role.

The provided Azure roles must exist for this call to succeed. See the Azure secrets roles docs for more information about roles.

Supported methods:

POST: /{mount_point}/roles/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Name of the role.

  • azure_roles (list(dict)) – List of Azure roles to be assigned to the generated service principal.

  • ttl (str | unicode) – Specifies the default TTL for service principals generated using this role. Accepts time suffixed strings (“1h”) or an integer number of seconds. Defaults to the system/engine default TTL time.

  • max_ttl (str | unicode) – Specifies the maximum TTL for service principals generated using this role. Accepts time suffixed strings (“1h”) or an integer number of seconds. Defaults to the system/engine max TTL time.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_config(mount_point='azure')[source]

Delete the stored Azure configuration and credentials.

Supported methods:

DELETE: /auth/{mount_point}/config. Produces: 204 (empty body)

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

generate_credentials(name, mount_point='azure')[source]

Generate a new service principal based on the named role.

Supported methods:

GET: /{mount_point}/creds/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the role to create credentials against.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

list_roles(mount_point='azure')[source]

List all of the roles that are registered with the plugin.

Supported methods:

LIST: /{mount_point}/roles. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

read_config(mount_point='azure')[source]

Read the stored configuration, omitting client_secret.

Supported methods:

GET: /{mount_point}/config. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

class hvac.api.secrets_engines.Database(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Database Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/databases/index.html

Methods

configure(name, plugin_name[, …])

This endpoint configures the connection string used to communicate with the desired database.

create_role(name, db_name, creation_statements)

This endpoint creates or updates a role definition.

create_static_role(name, db_name, username, …)

This endpoint creates or updates a static role definition.

delete_connection(name[, mount_point])

This endpoint deletes a connection.

delete_role(name[, mount_point])

This endpoint deletes the role definition.

delete_static_role(name[, mount_point])

This endpoint deletes the static role definition.

generate_credentials(name[, mount_point])

This endpoint generates a new set of dynamic credentials based on the named role.

get_static_credentials(name[, mount_point])

This endpoint returns the current credentials based on the named static role.

list_connections([mount_point])

This endpoint returns a list of available connections.

list_roles([mount_point])

This endpoint returns a list of available roles.

list_static_roles([mount_point])

This endpoint returns a list of available static roles.

read_connection(name[, mount_point])

This endpoint returns the configuration settings for a connection.

read_role(name[, mount_point])

This endpoint queries the role definition.

reset_connection(name[, mount_point])

This endpoint closes a connection and it’s underlying plugin and restarts it with the configuration stored in the barrier.

rotate_root_credentials(name[, mount_point])

This endpoint is used to rotate the root superuser credentials stored for the database connection.

configure(name, plugin_name, verify_connection=None, allowed_roles=None, root_rotation_statements=None, mount_point='database', *args, **kwargs)[source]

This endpoint configures the connection string used to communicate with the desired database. In addition to the parameters listed here, each Database plugin has additional, database plugin specific, parameters for this endpoint. Please read the HTTP API for the plugin you’d wish to configure to see the full list of additional parameters.

Parameters
  • name (str | unicode) – Specifies the name for this database connection. This is specified as part of the URL.

  • plugin_name (str | unicode) – Specifies the name of the plugin to use for this connection.

  • verify_connection (bool) – Specifies if the connection is verified during initial configuration.

  • allowed_roles (list) – List of the roles allowed to use this connection. Defaults to empty (no roles), if contains a “*” any role can use this connection.

  • root_rotation_statements (list) – Specifies the database statements to be executed to rotate the root user’s credentials.

Returns

The response of the request.

Return type

requests.Response

create_role(name, db_name, creation_statements, default_ttl=None, max_ttl=None, revocation_statements=None, rollback_statements=None, renew_statements=None, mount_point='database')[source]

This endpoint creates or updates a role definition.

Parameters
  • name (str | unicode) – Specifies the database role to manage.

  • db_name (str | unicode) – The name of the database connection to use for this role.

  • creation_statements (list) – Specifies the database statements executed to create and configure a user.

  • default_ttl (int) – Specifies the TTL for the leases associated with this role.

  • max_ttl (int) – Specifies the maximum TTL for the leases associated with this role.

  • revocation_statements (list) – Specifies the database statements to be executed to revoke a user.

  • rollback_statements (list) – Specifies the database statements to be executed to rollback a create operation in the event of an error.

  • renew_statements (list) – Specifies the database statements to be executed to renew a user.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_static_role(name, db_name, username, rotation_statements, rotation_period=86400, mount_point='database')[source]

This endpoint creates or updates a static role definition.

Parameters
  • name (str | unicode) – Specifies the name of the role to create.

  • db_name (str | unicode) – The name of the database connection to use for this role.

  • username (str | unicode) – Specifies the database username that the Vault role name above corresponds to.

  • rotation_statements (list) – Specifies the database statements to be executed to rotate the password for the configured database user. Not every plugin type will support this functionality. See the plugin’s API page for more information on support and formatting for this parameter.

  • rotation_period (int) – Specifies the amount of time Vault should wait before rotating the password. The minimum is 5 seconds.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_connection(name, mount_point='database')[source]

This endpoint deletes a connection.

Parameters

name (str | unicode) – Specifies the name of the connection to delete.

Returns

The response of the request.

Return type

requests.Response

delete_role(name, mount_point='database')[source]

This endpoint deletes the role definition.

Parameters
  • name (str | unicode) – Specifies the name of the role to delete.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_static_role(name, mount_point='database')[source]

This endpoint deletes the static role definition.

Parameters
  • name (str | unicode) – Specifies the name of the role to delete.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

generate_credentials(name, mount_point='database')[source]

This endpoint generates a new set of dynamic credentials based on the named role.

Parameters
  • name (str | unicode) – Specifies the name of the role to create credentials against

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

get_static_credentials(name, mount_point='database')[source]

This endpoint returns the current credentials based on the named static role.

Parameters
  • name (str | unicode) – Specifies the name of the role to create credentials against

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_connections(mount_point='database')[source]

This endpoint returns a list of available connections.

Returns

The response of the request.

Return type

requests.Response

list_roles(mount_point='database')[source]

This endpoint returns a list of available roles.

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_static_roles(mount_point='database')[source]

This endpoint returns a list of available static roles.

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_connection(name, mount_point='database')[source]

This endpoint returns the configuration settings for a connection.

Parameters

name (str | unicode) – Specifies the name of the connection to read.

Returns

The response of the request.

Return type

requests.Response

read_role(name, mount_point='database')[source]

This endpoint queries the role definition.

Parameters
  • name (str | unicode) – Specifies the name of the role to read.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

reset_connection(name, mount_point='database')[source]

This endpoint closes a connection and it’s underlying plugin and restarts it with the configuration stored in the barrier.

Parameters

name (str | unicode) – Specifies the name of the connection to reset.

Returns

The response of the request.

Return type

requests.Response

rotate_root_credentials(name, mount_point='database')[source]

This endpoint is used to rotate the root superuser credentials stored for the database connection. This user must have permissions to update its own password.

Parameters

name (str | unicode) – Specifies the name of the connection to rotate.

Returns

The response of the request.

Return type

requests.Response

class hvac.api.secrets_engines.Gcp(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Google Cloud Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/gcp/index.html

Methods

configure([credentials, ttl, max_ttl, …])

Configure shared information for the Gcp secrets engine.

create_or_update_roleset(name, project, bindings)

Create a roleset or update an existing roleset.

delete_roleset(name[, mount_point])

Delete an existing roleset by the given name.

generate_oauth2_access_token(roleset[, …])

Generate an OAuth2 token with the scopes defined on the roleset.

generate_service_account_key(roleset[, …])

Generate Secret (IAM Service Account Creds): Service Account Key

list_rolesets([mount_point])

List configured rolesets.

read_config([mount_point])

Read the configured shared information for the Gcp secrets engine.

read_roleset(name[, mount_point])

Read a roleset.

rotate_roleset_account(name[, mount_point])

Rotate the service account this roleset uses to generate secrets.

rotate_roleset_account_key(name[, mount_point])

Rotate the service account key this roleset uses to generate access tokens.

configure(credentials=None, ttl=None, max_ttl=None, mount_point='gcp')[source]

Configure shared information for the Gcp secrets engine.

Supported methods:

POST: /{mount_point}/config. Produces: 204 (empty body)

Parameters
  • credentials (str | unicode) – JSON credentials (either file contents or @path/to/file’) See docs for alternative ways to pass in to this parameter, as well as the required permissions.

  • ttl (int | str) – – Specifies default config TTL for long-lived credentials (i.e. service account keys). Accepts integer number of seconds or Go duration format string.

  • max_ttl (int | str) – Specifies the maximum config TTL for long-lived credentials (i.e. service account keys). Accepts integer number of seconds or Go duration format string.**

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_or_update_roleset(name, project, bindings, secret_type=None, token_scopes=None, mount_point='gcp')[source]

Create a roleset or update an existing roleset.

See roleset docs for the GCP secrets backend to learn more about what happens when you create or update a

roleset.

Supported methods:

POST: /{mount_point}/roleset/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Name of the role. Cannot be updated.

  • project (str | unicode) – Name of the GCP project that this roleset’s service account will belong to. Cannot be updated.

  • bindings (str | unicode) – Bindings configuration string (expects HCL or JSON format in raw or base64-encoded string)

  • secret_type (str | unicode) – Cannot be updated.

  • token_scopes (list[str]) – List of OAuth scopes to assign to access_token secrets generated under this role set (access_token role sets only)

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_roleset(name, mount_point='gcp')[source]

Delete an existing roleset by the given name.

Supported methods:

DELETE: /{mount_point}/roleset/{name} Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

generate_oauth2_access_token(roleset, mount_point='gcp')[source]

Generate an OAuth2 token with the scopes defined on the roleset.

This OAuth access token can be used in GCP API calls, e.g. curl -H “Authorization: Bearer $TOKEN” …

Supported methods:

GET: /{mount_point}/token/{roleset}. Produces: 200 application/json

Parameters
  • roleset (str | unicode) – Name of an roleset with secret type access_token to generate access_token under.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

generate_service_account_key(roleset, key_algorithm='KEY_ALG_RSA_2048', key_type='TYPE_GOOGLE_CREDENTIALS_FILE', method='POST', mount_point='gcp')[source]

Generate Secret (IAM Service Account Creds): Service Account Key

If using GET (‘read’), the optional parameters will be set to their defaults. Use POST if you want to specify

different values for these params.

Parameters
  • roleset (str | unicode) – Name of an roleset with secret type service_account_key to generate key under.

  • key_algorithm (str | unicode) – Key algorithm used to generate key. Defaults to 2k RSA key You probably should not choose other values (i.e. 1k),

  • key_type (str | unicode) – Private key type to generate. Defaults to JSON credentials file.

  • method (str | unicode) – Supported methods: POST: /{mount_point}/key/{roleset}. Produces: 200 application/json GET: /{mount_point}/key/{roleset}. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_rolesets(mount_point='gcp')[source]

List configured rolesets.

Supported methods:

LIST: /{mount_point}/rolesets. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_config(mount_point='gcp')[source]

Read the configured shared information for the Gcp secrets engine.

Credentials will be omitted from returned data.

Supported methods:

GET: /{mount_point}/config. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_roleset(name, mount_point='gcp')[source]

Read a roleset.

Supported methods:

GET: /{mount_point}/roleset/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

rotate_roleset_account(name, mount_point='gcp')[source]

Rotate the service account this roleset uses to generate secrets.

This also replaces the key access_token roleset. This can be used to invalidate old secrets generated by the

roleset or fix issues if a roleset’s service account (and/or keys) was changed outside of Vault (i.e. through GCP APIs/cloud console).

Supported methods:

POST: /{mount_point}/roleset/{name}/rotate. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

rotate_roleset_account_key(name, mount_point='gcp')[source]

Rotate the service account key this roleset uses to generate access tokens.

This does not recreate the roleset service account.

Supported methods:

POST: /{mount_point}/roleset/{name}/rotate-key. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

class hvac.api.secrets_engines.Identity(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Identity Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/identity/entity.html

Methods

configure_tokens_backend([issuer, mount_point])

Update configurations for OIDC-compliant identity tokens issued by Vault.

create_named_key(name[, rotation_period, …])

Create or update a named key which is used by a role to sign tokens.

create_or_update_entity(name[, entity_id, …])

Create or update an Entity.

create_or_update_entity_alias(name, …[, …])

Create a new alias for an entity.

create_or_update_entity_by_name(name[, …])

Create or update an entity by a given name.

create_or_update_group(name[, group_id, …])

Create or update a Group.

create_or_update_group_alias(name[, …])

Creates or update a group alias.

create_or_update_group_by_name(name[, …])

Create or update a group by its name.

create_or_update_role(name, key[, template, …])

Create or update a role.

delete_entity(entity_id[, mount_point])

Delete an entity and all its associated aliases.

delete_entity_alias(alias_id[, mount_point])

Delete a entity alias.

delete_entity_by_name(name[, mount_point])

Delete an entity and all its associated aliases, given the entity name.

delete_group(group_id[, mount_point])

Delete a group.

delete_group_alias(entity_id[, mount_point])

Delete a group alias.

delete_group_by_name(name[, mount_point])

Delete a group, given its name.

delete_named_key(name[, mount_point])

Delete a named key.

delete_role(name[, mount_point])

Deletes a role.

generate_signed_id_token(name[, mount_point])

Generate a signed ID (OIDC) token.

introspect_signed_id_token(token[, …])

Verify the authenticity and active state of a signed ID token.

list_entities([method, mount_point])

List available entities entities by their identifiers.

list_entities_by_name([method, mount_point])

List available entities by their names.

list_entity_aliases([method, mount_point])

List available entity aliases by their identifiers.

list_group_aliases([method, mount_point])

List available group aliases by their identifiers.

list_groups([method, mount_point])

List available groups by their identifiers.

list_groups_by_name([method, mount_point])

List available groups by their names.

list_named_keys([mount_point])

List all named keys.

list_roles([mount_point])

This endpoint will list all signing keys.

lookup_entity([name, entity_id, alias_id, …])

Query an entity based on the given criteria.

lookup_group([name, group_id, alias_id, …])

Query a group based on the given criteria.

merge_entities(from_entity_ids, to_entity_id)

Merge many entities into one entity.

read_active_public_keys([mount_point])

Retrieve the public portion of named keys.

read_entity(entity_id[, mount_point])

Query an entity by its identifier.

read_entity_alias(alias_id[, mount_point])

Query the entity alias by its identifier.

read_entity_by_name(name[, mount_point])

Query an entity by its name.

read_group(group_id[, mount_point])

Query the group by its identifier.

read_group_alias(alias_id[, mount_point])

Query the group alias by its identifier.

read_group_by_name(name[, mount_point])

Query a group by its name.

read_named_key(name[, mount_point])

Query a named key and returns its configurations.

read_role(name[, mount_point])

Query a role and returns its configuration.

read_tokens_backend_configuration([mount_point])

Query vault identity tokens configurations.

read_well_known_configurations([mount_point])

Retrieve a set of claims about the identity tokens’ configuration.

rotate_named_key(name, verification_ttl[, …])

Rotate a named key.

update_entity(entity_id[, name, metadata, …])

Update an existing entity.

update_entity_alias(alias_id, name, …[, …])

Update an existing entity alias.

update_group(group_id, name[, group_type, …])

Update an existing group.

update_group_alias(entity_id, name[, …])

Update an existing group alias.

validate_member_id_params_for_group_type(…)

Determine whether member ID parameters can be sent with a group create / update request.

configure_tokens_backend(issuer=None, mount_point='identity')[source]

Update configurations for OIDC-compliant identity tokens issued by Vault.

Supported methods:

POST: {mount_point}/oidc/config.

Parameters
  • issuer (str | unicode) – Issuer URL to be used in the iss claim of the token. If not set, Vault’s api_addr will be used. The issuer is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components, but no query or fragment components.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The a dict or the response of the configure_tokens_backend request. dict returned when messages are included in the response body.

Return type

requests.Response

create_named_key(name, rotation_period='24h', verification_ttl='24h', allowed_client_ids=None, algorithm='RS256', mount_point='identity')[source]

Create or update a named key which is used by a role to sign tokens.

Supported methods:

POST: {mount_point}/oidc/key/:name.

Parameters
  • name (str | unicode) – Name of the named key.

  • rotation_period (str | unicode) – How often to generate a new signing key. Can be specified as a number of seconds or as a time string like “30m” or “6h”.

  • verification_ttl (str | unicode) – Controls how long the public portion of a signing key will be available for verification after being rotated.

  • allowed_client_ids (list) – List of role client ids allowed to use this key for signing. If empty, no roles are allowed. If “*”, all roles are allowed.

  • algorithm (str | unicode) – Signing algorithm to use. Allowed values are: RS256 (default), RS384, RS512, ES256, ES384, ES512, EdDSA.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the create_a_named_key request.

Return type

dict

create_or_update_entity(name, entity_id=None, metadata=None, policies=None, disabled=None, mount_point='identity')[source]

Create or update an Entity.

Supported methods:

POST: /{mount_point}/entity. Produces: 200 application/json

Parameters
  • entity_id (str | unicode) – ID of the entity. If set, updates the corresponding existing entity.

  • name (str | unicode) – Name of the entity.

  • metadata (dict) – Metadata to be associated with the entity.

  • policies (str | unicode) – Policies to be tied to the entity.

  • disabled (bool) – Whether the entity is disabled. Disabled entities’ associated tokens cannot be used, but are not revoked.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response for creates, the generic response object for updates, of the request.

Return type

dict | requests.Response

create_or_update_entity_alias(name, canonical_id, mount_accessor, alias_id=None, mount_point='identity')[source]

Create a new alias for an entity.

Supported methods:

POST: /{mount_point}/entity-alias. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the alias. Name should be the identifier of the client in the authentication source. For example, if the alias belongs to userpass backend, the name should be a valid username within userpass backend. If alias belongs to GitHub, it should be the GitHub username.

  • alias_id (str | unicode) – ID of the entity alias. If set, updates the corresponding entity alias.

  • canonical_id (str | unicode) – Entity ID to which this alias belongs to.

  • mount_accessor (str | unicode) – Accessor of the mount to which the alias should belong to.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

create_or_update_entity_by_name(name, metadata=None, policies=None, disabled=None, mount_point='identity')[source]

Create or update an entity by a given name.

Supported methods:

POST: /{mount_point}/entity/name/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the entity.

  • metadata (dict) – Metadata to be associated with the entity.

  • policies (str | unicode) – Policies to be tied to the entity.

  • disabled (bool) – Whether the entity is disabled. Disabled entities’ associated tokens cannot be used, but are not revoked.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response for creates, the generic response of the request for updates.

Return type

requests.Response | dict

create_or_update_group(name, group_id=None, group_type='internal', metadata=None, policies=None, member_group_ids=None, member_entity_ids=None, mount_point='identity')[source]

Create or update a Group.

Supported methods:

POST: /{mount_point}/group. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the group.

  • group_id (str | unicode) – ID of the group. If set, updates the corresponding existing group.

  • group_type (str | unicode) – Type of the group, internal or external. Defaults to internal.

  • metadata (dict) – Metadata to be associated with the group.

  • policies (str | unicode) – Policies to be tied to the group.

  • member_group_ids (str | unicode) – Group IDs to be assigned as group members.

  • member_entity_ids (str | unicode) – Entity IDs to be assigned as group members.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response where available, otherwise the generic response object, of the request.

Return type

dict | requests.Response

create_or_update_group_alias(name, alias_id=None, mount_accessor=None, canonical_id=None, mount_point='identity')[source]

Creates or update a group alias.

Supported methods:

POST: /{mount_point}/group-alias. Produces: 200 application/json

Parameters
  • alias_id (str | unicode) – ID of the group alias. If set, updates the corresponding existing group alias.

  • name (str | unicode) – Name of the group alias.

  • mount_accessor (str | unicode) – Mount accessor to which this alias belongs to

  • canonical_id (str | unicode) – ID of the group to which this is an alias.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

create_or_update_group_by_name(name, group_type=None, metadata=None, policies=None, member_group_ids=None, member_entity_ids=None, mount_point='identity')[source]

Create or update a group by its name.

Supported methods:

POST: /{mount_point}/group/name/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the group.

  • group_type (str | unicode) – Type of the group, internal or external. Defaults to internal.

  • metadata (dict) – Metadata to be associated with the group.

  • policies (str | unicode) – Policies to be tied to the group.

  • member_group_ids (str | unicode) – Group IDs to be assigned as group members.

  • member_entity_ids (str | unicode) – Entity IDs to be assigned as group members.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_or_update_role(name, key, template=None, client_id=None, ttl='24h', mount_point='identity')[source]

Create or update a role.

ID tokens are generated against a role and signed against a named key.

Supported methods:

POST: {mount_point}/oidc/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • key (str | unicode) – A configured named key, the key must already exist.

  • template (str | unicode) – The template string to use for generating tokens. This may be in stringified JSON or base64 format.

  • client_id (str | unicode) – Optional client ID. A random ID will be generated if left unset.

  • ttl (str | unicode) – TTL of the tokens generated against the role. Can be specified as a number of seconds or as a time string like “30m” or “6h”.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the create_or_update_a_role request.

Return type

dict

delete_entity(entity_id, mount_point='identity')[source]

Delete an entity and all its associated aliases.

Supported methods:

DELETE: /{mount_point}/entity/id/:id. Produces: 204 (empty body)

Parameters
  • entity_id (str) – Identifier of the entity.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_entity_alias(alias_id, mount_point='identity')[source]

Delete a entity alias.

Supported methods:

DELETE: /{mount_point}/entity-alias/id/{alias_id}. Produces: 204 (empty body)

Parameters
  • alias_id (str | unicode) – Identifier of the entity.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_entity_by_name(name, mount_point='identity')[source]

Delete an entity and all its associated aliases, given the entity name.

Supported methods:

DELETE: /{mount_point}/entity/name/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Name of the entity.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_group(group_id, mount_point='identity')[source]

Delete a group.

Supported methods:

DELETE: /{mount_point}/group/id/{id}. Produces: 204 (empty body)

Parameters
  • group_id (str | unicode) – Identifier of the entity.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_group_alias(entity_id, mount_point='identity')[source]

Delete a group alias.

Supported methods:

DELETE: /{mount_point}/group-alias/id/{id}. Produces: 204 (empty body)

Parameters
  • entity_id (str | unicode) – ID of the group alias.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_group_by_name(name, mount_point='identity')[source]

Delete a group, given its name.

Supported methods:

DELETE: /{mount_point}/group/name/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Name of the group.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_named_key(name, mount_point='identity')[source]

Delete a named key.

Supported methods:

DELETE: {mount_point}/oidc/key/:name.

Parameters
  • name (str | unicode) – Name of the key.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the delete_a_named_key request.

Return type

dict

delete_role(name, mount_point='identity')[source]

Deletes a role.

Supported methods:

DELETE: {mount_point}/oidc/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the delete_a_role request.

Return type

dict

generate_signed_id_token(name, mount_point='identity')[source]

Generate a signed ID (OIDC) token.

Supported methods:

GET: {mount_point}/oidc/token/:name.

Parameters
  • name (str | unicode) – The name of the role against which to generate a signed ID token

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the generate_a_signed_id_token request.

Return type

dict

introspect_signed_id_token(token, client_id=None, mount_point='identity')[source]

Verify the authenticity and active state of a signed ID token.

Supported methods:

POST: {mount_point}/oidc/introspect.

Parameters
  • token (str | unicode) – A signed OIDC compliant ID token

  • client_id (str | unicode) – Specifying the client ID optimizes validation time

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the introspect_a_signed_id_token request.

Return type

dict

list_entities(method='LIST', mount_point='identity')[source]

List available entities entities by their identifiers.

Parameters
  • method (str | unicode) – Supported methods: LIST: /{mount_point}/entity/id. Produces: 200 application/json GET: /{mount_point}/entity/id?list=true. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_entities_by_name(method='LIST', mount_point='identity')[source]

List available entities by their names.

Parameters
  • method (str | unicode) – Supported methods: LIST: /{mount_point}/entity/name. Produces: 200 application/json GET: /{mount_point}/entity/name?list=true. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_entity_aliases(method='LIST', mount_point='identity')[source]

List available entity aliases by their identifiers.

Parameters
  • method (str | unicode) – Supported methods: LIST: /{mount_point}/entity-alias/id. Produces: 200 application/json GET: /{mount_point}/entity-alias/id?list=true. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The the JSON response of the request.

Return type

dict

list_group_aliases(method='LIST', mount_point='identity')[source]

List available group aliases by their identifiers.

Parameters
  • method (str | unicode) – Supported methods: LIST: /{mount_point}/group-alias/id. Produces: 200 application/json GET: /{mount_point}/group-alias/id?list=true. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The “data” key from the JSON response of the request.

Return type

dict

list_groups(method='LIST', mount_point='identity')[source]

List available groups by their identifiers.

Parameters
  • method (str | unicode) – Supported methods: LIST: /{mount_point}/group/id. Produces: 200 application/json GET: /{mount_point}/group/id?list=true. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_groups_by_name(method='LIST', mount_point='identity')[source]

List available groups by their names.

Parameters
  • method (str | unicode) – Supported methods: LIST: /{mount_point}/group/name. Produces: 200 application/json GET: /{mount_point}/group/name?list=true. Produces: 200 application/json

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_named_keys(mount_point='identity')[source]

List all named keys.

Supported methods:

LIST: {mount_point}/oidc/key.

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the list_named_keys request.

Return type

dict

list_roles(mount_point='identity')[source]

This endpoint will list all signing keys.

Supported methods:

LIST: {mount_point}/oidc/role.

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the list_roles request.

Return type

dict

lookup_entity(name=None, entity_id=None, alias_id=None, alias_name=None, alias_mount_accessor=None, mount_point='identity')[source]

Query an entity based on the given criteria.

The criteria can be name, id, alias_id, or a combination of alias_name and alias_mount_accessor.

Supported methods:

POST: /{mount_point}/lookup/entity. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the entity.

  • entity_id (str | unicode) – ID of the entity.

  • alias_id (str | unicode) – ID of the alias.

  • alias_name (str | unicode) – Name of the alias. This should be supplied in conjunction with alias_mount_accessor.

  • alias_mount_accessor (str | unicode) – Accessor of the mount to which the alias belongs to. This should be supplied in conjunction with alias_name.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request if a entity / entity alias is found in the lookup, None otherwise.

Return type

dict | None

lookup_group(name=None, group_id=None, alias_id=None, alias_name=None, alias_mount_accessor=None, mount_point='identity')[source]

Query a group based on the given criteria.

The criteria can be name, id, alias_id, or a combination of alias_name and alias_mount_accessor.

Supported methods:

POST: /{mount_point}/lookup/group. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the group.

  • group_id (str | unicode) – ID of the group.

  • alias_id (str | unicode) – ID of the alias.

  • alias_name (str | unicode) – Name of the alias. This should be supplied in conjunction with alias_mount_accessor.

  • alias_mount_accessor (str | unicode) – Accessor of the mount to which the alias belongs to. This should be supplied in conjunction with alias_name.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request if a group / group alias is found in the lookup, None otherwise.

Return type

dict | None

merge_entities(from_entity_ids, to_entity_id, force=None, mount_point='identity')[source]

Merge many entities into one entity.

Supported methods:

POST: /{mount_point}/entity/merge. Produces: 204 (empty body)

Parameters
  • from_entity_ids (array) – Entity IDs which needs to get merged.

  • to_entity_id (str | unicode) – Entity ID into which all the other entities need to get merged.

  • force (bool) – Setting this will follow the ‘mine’ strategy for merging MFA secrets. If there are secrets of the same type both in entities that are merged from and in entity into which all others are getting merged, secrets in the destination will be unaltered. If not set, this API will throw an error containing all the conflicts.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_active_public_keys(mount_point='identity')[source]

Retrieve the public portion of named keys.

Clients can use this to validate the authenticity of an identity token.

Supported methods:

GET: {mount_point}/oidc/.well-known/openid-configuration.

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the read_active_public_keys request.

Return type

dict

read_entity(entity_id, mount_point='identity')[source]

Query an entity by its identifier.

Supported methods:

GET: /auth/{mount_point}/entity/id/{id}. Produces: 200 application/json

Parameters
  • entity_id (str) – Identifier of the entity.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_entity_alias(alias_id, mount_point='identity')[source]

Query the entity alias by its identifier.

Supported methods:

GET: /{mount_point}/entity-alias/id/{id}. Produces: 200 application/json

Parameters
  • alias_id (str | unicode) – Identifier of entity alias.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_entity_by_name(name, mount_point='identity')[source]

Query an entity by its name.

Supported methods:

GET: /{mount_point}/entity/name/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the entity.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

read_group(group_id, mount_point='identity')[source]

Query the group by its identifier.

Supported methods:

GET: /{mount_point}/group/id/{id}. Produces: 200 application/json

Parameters
  • group_id (str | unicode) – Identifier of the group.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

read_group_alias(alias_id, mount_point='identity')[source]

Query the group alias by its identifier.

Supported methods:

GET: /{mount_point}/group-alias/id/:id. Produces: 200 application/json

Parameters
  • alias_id (str | unicode) – ID of the group alias.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_group_by_name(name, mount_point='identity')[source]

Query a group by its name.

Supported methods:

GET: /{mount_point}/group/name/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the group.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_named_key(name, mount_point='identity')[source]

Query a named key and returns its configurations.

Supported methods:

GET: {mount_point}/oidc/key/:name.

Parameters
  • name (str | unicode) – Name of the key.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the read_a_named_key request.

Return type

dict

read_role(name, mount_point='identity')[source]

Query a role and returns its configuration.

Supported methods:

GET: {mount_point}/oidc/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the read_a_role request.

Return type

dict

read_tokens_backend_configuration(mount_point='identity')[source]

Query vault identity tokens configurations.

Supported methods:

GET: {mount_point}/oidc/config.

Returns

The response of the read_tokens_backend_configuration request.

Return type

dict

read_well_known_configurations(mount_point='identity')[source]

Retrieve a set of claims about the identity tokens’ configuration.

The response is a compliant OpenID Provider Configuration Response.

Supported methods:

GET: {mount_point}/oidc/.well-known/openid-configuration.

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the read_well_known_configurations request.

Return type

dict

rotate_named_key(name, verification_ttl, mount_point='identity')[source]

Rotate a named key.

Supported methods:

POST: {mount_point}/oidc/key/:name/rotate.

Parameters
  • name (str | unicode) – Name of the key to be rotated.

  • verification_ttl (str | unicode) – Controls how long the public portion of the key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the rotate_a_named_key request.

Return type

dict

update_entity(entity_id, name=None, metadata=None, policies=None, disabled=None, mount_point='identity')[source]

Update an existing entity.

Supported methods:

POST: /{mount_point}/entity/id/{id}. Produces: 200 application/json

Parameters
  • entity_id (str | unicode) – Identifier of the entity.

  • name (str | unicode) – Name of the entity.

  • metadata (dict) – Metadata to be associated with the entity.

  • policies (str | unicode) – Policies to be tied to the entity.

  • disabled (bool) – Whether the entity is disabled. Disabled entities’ associated tokens cannot be used, but are not revoked.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response where available, otherwise the generic response object, of the request.

Return type

dict | requests.Response

update_entity_alias(alias_id, name, canonical_id, mount_accessor, mount_point='identity')[source]

Update an existing entity alias.

Supported methods:

POST: /{mount_point}/entity-alias/id/{id}. Produces: 200 application/json

Parameters
  • alias_id (str | unicode) – Identifier of the entity alias.

  • name (str | unicode) – Name of the alias. Name should be the identifier of the client in the authentication source. For example, if the alias belongs to userpass backend, the name should be a valid username within userpass backend. If alias belongs to GitHub, it should be the GitHub username.

  • canonical_id (str | unicode) – Entity ID to which this alias belongs to.

  • mount_accessor (str | unicode) – Accessor of the mount to which the alias should belong to.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response where available, otherwise the generic response object, of the request.

Return type

dict | requests.Response

update_group(group_id, name, group_type=None, metadata=None, policies=None, member_group_ids=None, member_entity_ids=None, mount_point='identity')[source]

Update an existing group.

Supported methods:

POST: /{mount_point}/group/id/{id}. Produces: 200 application/json

Parameters
  • group_id (str | unicode) – Identifier of the entity.

  • name (str | unicode) – Name of the group.

  • group_type (str | unicode) – Type of the group, internal or external. Defaults to internal.

  • metadata (dict) – Metadata to be associated with the group.

  • policies (str | unicode) – Policies to be tied to the group.

  • member_group_ids (str | unicode) – Group IDs to be assigned as group members.

  • member_entity_ids (str | unicode) – Entity IDs to be assigned as group members.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response where available, otherwise the generic response object, of the request.

Return type

dict | requests.Response

update_group_alias(entity_id, name, mount_accessor=None, canonical_id=None, mount_point='identity')[source]

Update an existing group alias.

Supported methods:

POST: /{mount_point}/group-alias/id/{id}. Produces: 200 application/json

Parameters
  • entity_id (str | unicode) – ID of the group alias.

  • name (str | unicode) – Name of the group alias.

  • mount_accessor (str | unicode) – Mount accessor to which this alias belongs toMount accessor to which this alias belongs to.

  • canonical_id (str | unicode) – ID of the group to which this is an alias.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

static validate_member_id_params_for_group_type(group_type, params, member_group_ids, member_entity_ids)[source]

Determine whether member ID parameters can be sent with a group create / update request.

These parameters are only allowed for the internal group type. If they’re set for an external group type, Vault returns a “error” response.

Parameters
  • group_type (str | unicode) – Type of the group, internal or external

  • params (dict) – Params dict to conditionally add the member entity/group ID’s to.

  • member_group_ids (str | unicode) – Group IDs to be assigned as group members.

  • member_entity_ids (str | unicode) – Entity IDs to be assigned as group members.

Returns

Params dict with conditionally added member entity/group ID’s.

Return type

dict

class hvac.api.secrets_engines.Kv(adapter, default_kv_version='2')[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Class containing methods for the key/value secrets_engines backend API routes. Reference: https://www.vaultproject.io/docs/secrets/kv/index.html

Methods

__init__(adapter[, default_kv_version])

Create a new Kv instance.

Attributes

allowed_kv_versions

Built-in mutable sequence.

default_kv_version

v1

Accessor for kv version 1 class / method.

v2

Accessor for kv version 2 class / method.

__init__(adapter, default_kv_version='2')[source]

Create a new Kv instance.

Parameters
  • adapter (hvac.adapters.Adapter) – Instance of hvac.adapters.Adapter; used for performing HTTP requests.

  • default_kv_version (str | unicode) – KV version number (e.g., ‘1’) to use as the default when accessing attributes/methods under this class.

allowed_kv_versions = ['1', '2']
property default_kv_version
property v1

Accessor for kv version 1 class / method. Provided via the hvac.api.secrets_engines.kv_v1.KvV1 class.

Returns

This Kv instance’s associated KvV1 instance.

Return type

hvac.api.secrets_engines.kv_v1.KvV1

property v2

Accessor for kv version 2 class / method. Provided via the hvac.api.secrets_engines.kv_v2.KvV2 class.

Returns

This Kv instance’s associated KvV2 instance.

Return type

hvac.api.secrets_engines.kv_v2.KvV2

class hvac.api.secrets_engines.KvV1(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

KV Secrets Engine - Version 1 (API).

Reference: https://www.vaultproject.io/api/secrets/kv/kv-v1.html

Methods

create_or_update_secret(path, secret[, …])

Store a secret at the specified location.

delete_secret(path[, mount_point])

Delete the secret at the specified location.

list_secrets(path[, mount_point])

Return a list of key names at the specified location.

read_secret(path[, mount_point])

Retrieve the secret at the specified location.

create_or_update_secret(path, secret, method=None, mount_point='secret')[source]

Store a secret at the specified location.

If the value does not yet exist, the calling token must have an ACL policy granting the create capability. If the value already exists, the calling token must have an ACL policy granting the update capability.

Supported methods:

POST: /{mount_point}/{path}. Produces: 204 (empty body) PUT: /{mount_point}/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secrets to create/update. This is specified as part of the URL.

  • secret (dict) – Specifies keys, paired with associated values, to be held at the given location. Multiple key/value pairs can be specified, and all will be returned on a read operation. A key called ttl will trigger some special behavior. See the Vault KV secrets engine documentation for details.

  • method (str | unicode) – Optional parameter to explicitly request a POST (create) or PUT (update) request to the selected kv secret engine. If no argument is provided for this parameter, hvac attempts to intelligently determine which method is appropriate.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the create_or_update_secret request.

Return type

requests.Response

delete_secret(path, mount_point='secret')[source]

Delete the secret at the specified location.

Supported methods:

DELETE: /{mount_point}/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the delete_secret request.

Return type

requests.Response

list_secrets(path, mount_point='secret')[source]

Return a list of key names at the specified location.

Folders are suffixed with /. The input must be a folder; list on a file will not return a value. Note that no policy-based filtering is performed on keys; do not encode sensitive information in key names. The values themselves are not accessible via this command.

Supported methods:

LIST: /{mount_point}/{path}. Produces: 200 application/json

Parameters
  • path (str | unicode) – Specifies the path of the secrets to list. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the list_secrets request.

Return type

dict

read_secret(path, mount_point='secret')[source]

Retrieve the secret at the specified location.

Supported methods:

GET: /{mount_point}/{path}. Produces: 200 application/json

Parameters
  • path (str | unicode) – Specifies the path of the secret to read. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the read_secret request.

Return type

dict

class hvac.api.secrets_engines.KvV2(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

KV Secrets Engine - Version 2 (API).

Reference: https://www.vaultproject.io/api/secret/kv/kv-v2.html

Methods

configure([max_versions, cas_required, …])

Configure backend level settings that are applied to every key in the key-value store.

create_or_update_secret(path, secret[, cas, …])

Create a new version of a secret at the specified location.

delete_latest_version_of_secret(path[, …])

Issue a soft delete of the secret’s latest version at the specified location.

delete_metadata_and_all_versions(path[, …])

Delete (permanently) the key metadata and all version data for the specified key.

delete_secret_versions(path, versions[, …])

Issue a soft delete of the specified versions of the secret.

destroy_secret_versions(path, versions[, …])

Permanently remove the specified version data and numbers for the provided path from the key-value store.

list_secrets(path[, mount_point])

Return a list of key names at the specified location.

patch(path, secret[, mount_point])

Set or update data in the KV store without overwriting.

read_configuration([mount_point])

Read the KV Version 2 configuration.

read_secret_metadata(path[, mount_point])

Retrieve the metadata and versions for the secret at the specified path.

read_secret_version(path[, version, mount_point])

Retrieve the secret at the specified location.

undelete_secret_versions(path, versions[, …])

Undelete the data for the provided version and path in the key-value store.

update_metadata(path[, max_versions, …])

Updates the max_versions of cas_required setting on an existing path.

configure(max_versions=10, cas_required=None, mount_point='secret')[source]

Configure backend level settings that are applied to every key in the key-value store.

Supported methods:

POST: /{mount_point}/config. Produces: 204 (empty body)

Parameters
  • max_versions (int) – The number of versions to keep per key. This value applies to all keys, but a key’s metadata setting can overwrite this value. Once a key has more than the configured allowed versions the oldest version will be permanently deleted. Defaults to 10.

  • cas_required (bool) – If true all keys will require the cas parameter to be set on all write requests.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_or_update_secret(path, secret, cas=None, mount_point='secret')[source]

Create a new version of a secret at the specified location.

If the value does not yet exist, the calling token must have an ACL policy granting the create capability. If the value already exists, the calling token must have an ACL policy granting the update capability.

Supported methods:

POST: /{mount_point}/data/{path}. Produces: 200 application/json

Parameters
  • path (str | unicode) – Path

  • cas (int) – Set the “cas” value to use a Check-And-Set operation. If not set the write will be allowed. If set to 0 a write will only be allowed if the key doesn’t exist. If the index is non-zero the write will only be allowed if the key’s current version matches the version specified in the cas parameter.

  • secret (dict) – The contents of the “secret” dict will be stored and returned on read.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the request.

Return type

dict

delete_latest_version_of_secret(path, mount_point='secret')[source]

Issue a soft delete of the secret’s latest version at the specified location.

This marks the version as deleted and will stop it from being returned from reads, but the underlying data will not be removed. A delete can be undone using the undelete path.

Supported methods:

DELETE: /{mount_point}/data/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_metadata_and_all_versions(path, mount_point='secret')[source]

Delete (permanently) the key metadata and all version data for the specified key.

All version history will be removed.

Supported methods:

DELETE: /{mount_point}/metadata/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_secret_versions(path, versions, mount_point='secret')[source]

Issue a soft delete of the specified versions of the secret.

This marks the versions as deleted and will stop them from being returned from reads, but the underlying data will not be removed. A delete can be undone using the undelete path.

Supported methods:

POST: /{mount_point}/delete/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.

  • versions (int) – The versions to be deleted. The versioned data will not be deleted, but it will no longer be returned in normal get requests.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

destroy_secret_versions(path, versions, mount_point='secret')[source]

Permanently remove the specified version data and numbers for the provided path from the key-value store.

Supported methods:

POST: /{mount_point}/destroy/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secret to destroy. This is specified as part of the URL.

  • versions (list of int) – The versions to destroy. Their data will be permanently deleted.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_secrets(path, mount_point='secret')[source]

Return a list of key names at the specified location.

Folders are suffixed with /. The input must be a folder; list on a file will not return a value. Note that no policy-based filtering is performed on keys; do not encode sensitive information in key names. The values themselves are not accessible via this command.

Supported methods:

LIST: /{mount_point}/metadata/{path}. Produces: 200 application/json

Parameters
  • path (str | unicode) – Specifies the path of the secrets to list. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the request.

Return type

dict

patch(path, secret, mount_point='secret')[source]

Set or update data in the KV store without overwriting.

Parameters
  • path (str | unicode) – Path

  • secret (dict) – The contents of the “secret” dict will be stored and returned on read.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the create_or_update_secret request.

Return type

dict

read_configuration(mount_point='secret')[source]

Read the KV Version 2 configuration.

Supported methods:

GET: /auth/{mount_point}/config. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_secret_metadata(path, mount_point='secret')[source]

Retrieve the metadata and versions for the secret at the specified path.

Supported methods:

GET: /{mount_point}/metadata/{path}. Produces: 200 application/json

Parameters
  • path (str | unicode) – Specifies the path of the secret to read. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_secret_version(path, version=None, mount_point='secret')[source]

Retrieve the secret at the specified location.

Supported methods:

GET: /{mount_point}/data/{path}. Produces: 200 application/json

Parameters
  • path (str | unicode) – Specifies the path of the secret to read. This is specified as part of the URL.

  • version (int) – Specifies the version to return. If not set the latest version is returned.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The JSON response of the request.

Return type

dict

undelete_secret_versions(path, versions, mount_point='secret')[source]

Undelete the data for the provided version and path in the key-value store.

This restores the data, allowing it to be returned on get requests.

Supported methods:

POST: /{mount_point}/undelete/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Specifies the path of the secret to undelete. This is specified as part of the URL.

  • versions (list of int) – The versions to undelete. The versions will be restored and their data will be returned on normal get requests.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

update_metadata(path, max_versions=None, cas_required=None, mount_point='secret')[source]

Updates the max_versions of cas_required setting on an existing path.

Supported methods:

POST: /{mount_point}/metadata/{path}. Produces: 204 (empty body)

Parameters
  • path (str | unicode) – Path

  • max_versions (int) – The number of versions to keep per key. If not set, the backend’s configured max version is used. Once a key has more than the configured allowed versions the oldest version will be permanently deleted.

  • cas_required (bool) – If true the key will require the cas parameter to be set on all write requests. If false, the backend’s configuration will be used.

  • mount_point (str | unicode) – The “path” the secret engine was mounted on.

Returns

The response of the request.

Return type

requests.Response

class hvac.api.secrets_engines.Pki(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Pki Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/pki/index.html

Methods

create_or_update_role(name[, extra_params, …])

Create/Update Role.

delete_role(name[, mount_point])

Delete Role.

delete_root([mount_point])

Delete Root.

generate_certificate(name, common_name[, …])

Generate Certificate.

generate_intermediate(type, common_name[, …])

Generate Intermediate.

generate_root(type, common_name[, …])

Generate Root.

list_certificates([mount_point])

List Certificates.

list_roles([mount_point])

List Roles.

read_ca_certificate([mount_point])

Read CA Certificate.

read_ca_certificate_chain([mount_point])

Read CA Certificate Chain.

read_certificate(serial[, mount_point])

Read Certificate.

read_crl([mount_point])

Read CRL.

read_crl_configuration([mount_point])

Read CRL Configuration.

read_role(name[, mount_point])

Read Role.

read_urls([mount_point])

Read URLs.

revoke_certificate(serial_number[, mount_point])

Revoke Certificate.

rotate_crl([mount_point])

Rotate CRLs.

set_crl_configuration([expiry, disable, …])

Set CRL Configuration.

set_signed_intermediate(certificate[, …])

Set Signed Intermediate.

set_urls(params[, mount_point])

Set URLs.

sign_certificate(name, csr, common_name[, …])

Sign Certificate.

sign_intermediate(csr, common_name[, …])

Sign Intermediate.

sign_self_issued(certificate[, mount_point])

Sign Self-Issued.

sign_verbatim(csr[, name, extra_params, …])

Sign Verbatim.

submit_ca_information(pem_bundle[, mount_point])

Submit CA Information.

tidy([extra_params, mount_point])

Tidy.

create_or_update_role(name, extra_params=None, mount_point='pki')[source]

Create/Update Role.

Creates or updates the role definition.

Supported methods:

POST: /{mount_point}/roles/{name}. Produces: 200 application/json

Parameters
  • name – The name of the role to create.

  • extra_params – A dictionary with extra parameters.

  • mount_point – The “path” the method/backend was mounted on.

Name name

str | unicode

Name extra_params

dict

Name mount_point

str | unicode

Returns

The JSON response of the request.

Rname

requests.Response

delete_role(name, mount_point='pki')[source]

Delete Role.

Deletes the role definition.

Supported methods:

DELETE: /{mount_point}/roles/{name}. Produces: 200 application/json

Parameters
  • name – The name of the role to delete.

  • mount_point – The “path” the method/backend was mounted on.

Name name

str | unicode

Name mount_point

str | unicode

Returns

The JSON response of the request.

Return type

requests.Response

delete_root(mount_point='pki')[source]

Delete Root.

Deletes the current CA key.

Supported methods:

DELETE: /{mount_point}/root. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

generate_certificate(name, common_name, extra_params=None, mount_point='pki', wrap_ttl=None)[source]

Generate Certificate.

Generates a new set of credentials (private key and certificate) based on the role named in the endpoint.

Supported methods:

POST: /{mount_point}/issue/{name}. Produces: 200 application/json

Parameters
  • name – The name of the role to create the certificate against.

  • common_name – The requested CN for the certificate.

  • extra_params – A dictionary with extra parameters.

  • mount_point – The “path” the method/backend was mounted on.

  • wrap_ttl (str | unicode) – Specifies response wrapping token creation with duration. IE: ’15s’, ‘20m’, ‘25h’.

Name name

str | unicode

Name common_name

str | unicode

Name extra_params

dict

Name mount_point

str | unicode

Returns

The JSON response of the request.

Return type

requests.Response

generate_intermediate(type, common_name, extra_params=None, mount_point='pki', wrap_ttl=None)[source]

Generate Intermediate.

Generates a new private key and a CSR for signing.

Supported methods:

POST: /{mount_point}/intermediate/generate/{type}. Produces: 200 application/json

Parameters
  • type (str | unicode) – Specifies the type to create. exported (private key also exported) or internal.

  • common_name (str | unicode) – Specifies the requested CN for the certificate.

  • extra_params (dict) – Dictionary with extra parameters.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

  • wrap_ttl (str | unicode) – Specifies response wrapping token creation with duration. IE: ’15s’, ‘20m’, ‘25h’.

Returns

The JSON response of the request.

Return type

requests.Response

generate_root(type, common_name, extra_params=None, mount_point='pki', wrap_ttl=None)[source]

Generate Root.

Generates a new self-signed CA certificate and private key.

Supported methods:

POST: /{mount_point}/root/generate/{type}. Produces: 200 application/json

Parameters
  • type (str | unicode) – Specifies the type to create. exported (private key also exported) or internal.

  • common_name (str | unicode) – The requested CN for the certificate.

  • extra_params (dict) – A dictionary with extra parameters.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

  • wrap_ttl (str | unicode) – Specifies response wrapping token creation with duration. IE: ’15s’, ‘20m’, ‘25h’.

Returns

The JSON response of the request.

Return type

requests.Response

list_certificates(mount_point='pki')[source]

List Certificates.

The list of the current certificates by serial number only.

Supported methods:

LIST: /{mount_point}/certs. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_roles(mount_point='pki')[source]

List Roles.

Get a list of available roles.

Supported methods:

LIST: /{mount_point}/roles. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_ca_certificate(mount_point='pki')[source]

Read CA Certificate.

Retrieves the CA certificate in raw DER-encoded form.

Supported methods:

GET: /{mount_point}/ca/pem. Produces: String

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The certificate as pem.

Return type

str

read_ca_certificate_chain(mount_point='pki')[source]

Read CA Certificate Chain.

Retrieves the CA certificate chain, including the CA in PEM format.

Supported methods:

GET: /{mount_point}/ca_chain. Produces: String

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The certificate chain as pem.

Return type

str

read_certificate(serial, mount_point='pki')[source]

Read Certificate.

Retrieves one of a selection of certificates.

Supported methods:

GET: /{mount_point}/cert/{serial}. Produces: 200 application/json

Parameters
  • serial (str | unicode) – the serial of the key to read.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_crl(mount_point='pki')[source]

Read CRL.

Retrieves the current CRL in PEM format. This endpoint is an unauthenticated.

Supported methods:

GET: /{mount_point}/crl/pem. Produces: 200 application/pkix-crl

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The content of the request e.g. CRL string representation.

Return type

str

read_crl_configuration(mount_point='pki')[source]

Read CRL Configuration.

Getting the duration for which the generated CRL should be marked valid.

Supported methods:

GET: /{mount_point}/config/crl. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_role(name, mount_point='pki')[source]

Read Role.

Queries the role definition.

Supported methods:

GET: /{mount_point}/roles/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – The name of the role to read.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_urls(mount_point='pki')[source]

Read URLs.

Fetches the URLs to be encoded in generated certificates.

Supported methods:

GET: /{mount_point}/config/urls. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

revoke_certificate(serial_number, mount_point='pki')[source]

Revoke Certificate.

Revokes a certificate using its serial number.

Supported methods:

POST: /{mount_point}/revoke. Produces: 200 application/json

Parameters
  • serial_number – The serial number of the certificate to revoke.

  • mount_point – The “path” the method/backend was mounted on.

Name serial_number

str | unicode

Name mount_point

str | unicode

Returns

The JSON response of the request.

Return type

requests.Response

rotate_crl(mount_point='pki')[source]

Rotate CRLs.

Forces a rotation of the CRL.

Supported methods:

GET: /{mount_point}/crl/rotate. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

set_crl_configuration(expiry=None, disable=None, extra_params=None, mount_point='pki')[source]

Set CRL Configuration.

Setting the duration for which the generated CRL should be marked valid. If the CRL is disabled, it will return a signed but zero-length CRL for any request. If enabled, it will re-build the CRL.

Supported methods:

POST: /{mount_point}/config/crl. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

set_signed_intermediate(certificate, mount_point='pki')[source]

Set Signed Intermediate.

Allows submitting the signed CA certificate corresponding to a private key generated via “Generate Intermediate”

Supported methods:

POST: /{mount_point}/intermediate/set-signed. Produces: 200 application/json

Parameters
  • certificate (str | unicode) – Specifies the certificate in PEM format.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

set_urls(params, mount_point='pki')[source]

Set URLs.

Setting the issuing certificate endpoints, CRL distribution points, and OCSP server endpoints that will be encoded into issued certificates. You can update any of the values at any time without affecting the other existing values. To remove the values, simply use a blank string as the parameter.

Supported methods:

POST: /{mount_point}/config/urls. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

sign_certificate(name, csr, common_name, extra_params=None, mount_point='pki')[source]

Sign Certificate.

Signs a new certificate based upon the provided CSR and the supplied parameters.

Supported methods:

POST: /{mount_point}/sign/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – The role to sign the certificate.

  • csr (str | unicode) – The PEM-encoded CSR.

  • common_name (str | unicode) – The requested CN for the certificate. If the CN is allowed by role policy, it will be issued.

  • extra_params (dict) – A dictionary with extra parameters.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

sign_intermediate(csr, common_name, extra_params=None, mount_point='pki')[source]

Sign Intermediate.

Issue a certificate with appropriate values for acting as an intermediate CA.

Supported methods:

POST: /{mount_point}/root/sign-intermediate. Produces: 200 application/json

Parameters
  • csr (str | unicode) – The PEM-encoded CSR.

  • common_name (str | unicode) – The requested CN for the certificate.

  • extra_params (dict) – Dictionary with extra parameters.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

sign_self_issued(certificate, mount_point='pki')[source]

Sign Self-Issued.

Sign a self-issued certificate.

Supported methods:

POST: /{mount_point}/root/sign-self-issued. Produces: 200 application/json

Parameters
  • certificate (str | unicode) – The PEM-encoded self-issued certificate.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

sign_verbatim(csr, name=False, extra_params=None, mount_point='pki')[source]

Sign Verbatim.

Signs a new certificate based upon the provided CSR.

Supported methods:

POST: /{mount_point}/sign-verbatim. Produces: 200 application/json

Parameters
  • csr (str | unicode) – The PEM-encoded CSR.

  • name (str | unicode) – Specifies a role.

  • extra_params (dict) – A dictionary with extra parameters.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

submit_ca_information(pem_bundle, mount_point='pki')[source]

Submit CA Information.

Submitting the CA information for the backend.

Supported methods:

POST: /{mount_point}/config/ca. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

tidy(extra_params=None, mount_point='pki')[source]

Tidy.

Allows tidying up the storage backend and/or CRL by removing certificates that have expired and are past a certain buffer period beyond their expiration time.

Supported methods:

POST: /{mount_point}/tidy. Produces: 200 application/json

Parameters
  • extra_params (dict) – A dictionary with extra parameters.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

requests.Response

class hvac.api.secrets_engines.RabbitMQ(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

RabbitMQ Secrets Engine (API). Reference: https://www.vaultproject.io/api/secret/rabbitmq/index.html

Methods

configure([connection_uri, username, …])

Configure shared information for the rabbitmq secrets engine.

configure_lease(ttl, max_ttl[, mount_point])

This endpoint configures the lease settings for generated credentials.

create_role(name[, tags, vhosts, …])

This endpoint creates or updates the role definition.

delete_role(name[, mount_point])

This endpoint deletes the role definition.

generate_credentials(name[, mount_point])

This endpoint generates a new set of dynamic credentials based on the named role.

read_role(name[, mount_point])

This endpoint queries the role definition.

configure(connection_uri='', username='', password='', verify_connection=True, mount_point='rabbitmq')[source]

Configure shared information for the rabbitmq secrets engine.

Supported methods:

POST: /{mount_point}/config/connection. Produces: 204 (empty body)

Parameters
  • connection_uri (str | unicode) – Specifies the RabbitMQ connection URI.

  • username (str | unicode) – Specifies the RabbitMQ management administrator username.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: rabbitmq).

Password

Specifies the RabbitMQ management administrator password.

Verify_connection

Specifies whether to verify connection URI, username, and password.

Returns

The response of the request.

Return type

requests.Response

configure_lease(ttl, max_ttl, mount_point='rabbitmq')[source]

This endpoint configures the lease settings for generated credentials.

Parameters
  • ttl (int) – Specifies the lease ttl provided in seconds.

  • max_ttl (int) – Specifies the maximum ttl provided in seconds.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: rabbitmq).

Returns

The JSON response of the request.

Return type

requests.Response

create_role(name, tags='', vhosts='', vhost_topics='', mount_point='rabbitmq')[source]

This endpoint creates or updates the role definition.

Parameters
  • name (str | unicode) – Specifies the name of the role to create.

  • tags (str | unicode) – Specifies a comma-separated RabbitMQ management tags.

  • vhosts (str | unicode) – pecifies a map of virtual hosts to permissions.

  • vhost_topics (str | unicode) – Specifies a map of virtual hosts and exchanges to topic permissions.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: rabbitmq).

Returns

The JSON response of the request.

Return type

requests.Response

delete_role(name, mount_point='rabbitmq')[source]

This endpoint deletes the role definition. Even if the role does not exist, this endpoint will still return a successful response.

Parameters
  • name (str | unicode) – Specifies the name of the role to delete.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: rabbitmq).

Returns

The response of the request.

Return type

requests.Response

generate_credentials(name, mount_point='rabbitmq')[source]

This endpoint generates a new set of dynamic credentials based on the named role.

Parameters
  • name (str | unicode) – Specifies the name of the role to create credentials against.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: rabbitmq).

Returns

The response of the request.

Return type

requests.Response

read_role(name, mount_point='rabbitmq')[source]

This endpoint queries the role definition.

Parameters
  • name (str | unicode) – Specifies the name of the role to read.

  • mount_point (str | unicode) – Specifies the place where the secrets engine will be accessible (default: rabbitmq).

Returns

The JSON response of the request.

Return type

requests.Response

class hvac.api.secrets_engines.SecretsEngines(adapter)[source]

Bases: hvac.api.vault_api_category.VaultApiCategory

Secrets Engines.

Attributes

implemented_classes

Built-in mutable sequence.

unimplemented_classes

Built-in mutable sequence.

implemented_classes = [<class 'hvac.api.secrets_engines.aws.Aws'>, <class 'hvac.api.secrets_engines.azure.Azure'>, <class 'hvac.api.secrets_engines.gcp.Gcp'>, <class 'hvac.api.secrets_engines.active_directory.ActiveDirectory'>, <class 'hvac.api.secrets_engines.identity.Identity'>, <class 'hvac.api.secrets_engines.kv.Kv'>, <class 'hvac.api.secrets_engines.pki.Pki'>, <class 'hvac.api.secrets_engines.transform.Transform'>, <class 'hvac.api.secrets_engines.transit.Transit'>, <class 'hvac.api.secrets_engines.database.Database'>, <class 'hvac.api.secrets_engines.consul.Consul'>, <class 'hvac.api.secrets_engines.rabbitmq.RabbitMQ'>]
unimplemented_classes = ['AliCloud', 'Azure', 'GcpKms', 'Nomad', 'Ssh', 'TOTP', 'Cassandra', 'MongoDb', 'Mssql', 'MySql', 'PostgreSql']
class hvac.api.secrets_engines.Transform(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Transform Secrets Engine (API).

Reference: https://www.vaultproject.io/api-docs/secret/transform

Methods

create_or_update_alphabet(name, alphabet[, …])

Create or update an alphabet with the given name.

create_or_update_role(name, transformations)

Creates or update the role with the given name.

create_or_update_template(name, …[, …])

Creates or update a template with the given name.

create_or_update_transformation(name, …[, …])

Create or update a transformation with the given name.

decode(role_name[, value, transformation, …])

Decode the provided value using a named role.

delete_alphabet(name[, mount_point])

Delete an existing alphabet by the given name.

delete_role(name[, mount_point])

Delete an existing role by the given name.

delete_template(name[, mount_point])

Delete an existing template by the given name.

delete_transformation(name[, mount_point])

Delete an existing transformation by the given name.

encode(role_name[, value, transformation, …])

Encode the provided value using a named role.

list_alphabets([mount_point])

List all existing alphabets in the secrets engine.

list_roles([mount_point])

List all existing roles in the secrets engine.

list_templates([mount_point])

List all existing templates in the secrets engine.

list_transformations([mount_point])

List all existing transformations in the secrets engine.

read_alphabet(name[, mount_point])

Queries an existing alphabet by the given name.

read_role(name[, mount_point])

Query an existing role by the given name.

read_template(name[, mount_point])

Query an existing template by the given name.

read_transformation(name[, mount_point])

Query an existing transformation by the given name.

create_or_update_alphabet(name, alphabet, mount_point='transform')[source]

Create or update an alphabet with the given name.

If an alphabet with the name does not exist, it will be created. If the alphabet exists, it will be updated with the new attributes.

Supported methods:

POST: /{mount_point}/alphabet/:name.

Parameters
  • name (str | unicode) – Specifies the name of the transformation alphabet to create.

  • alphabet (str | unicode) – the set of characters that can exist within the provided value and the encoded or decoded value for a FPE transformation.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the create_or_update_alphabet request.

Return type

requests.Response

create_or_update_role(name, transformations, mount_point='transform')[source]

Creates or update the role with the given name.

If a role with the name does not exist, it will be created. If the role exists, it will be updated with the new attributes.

Supported methods:

POST: /{mount_point}/role/:name.

Parameters
  • name (str | unicode) – the name of the role to create. This is part of the request URL.

  • transformations (list) – Specifies the transformations that can be used with this role. At least one transformation is required.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the create_or_update_role request.

Return type

requests.Response

create_or_update_template(name, template_type, pattern, alphabet, mount_point='transform')[source]

Creates or update a template with the given name.

If a template with the name does not exist, it will be created. If the template exists, it will be updated with the new attributes.

Supported methods:

POST: /{mount_point}/template/:name.

Parameters
  • name (str | unicode) – the name of the template to create.

  • template_type (str | unicode) – Specifies the type of pattern matching to perform. The ony type currently supported by this backend is regex.

  • pattern (str | unicode) – the pattern used to match a particular value. For regex type matching, capture group determines the set of character that should be matched against. Any matches outside of capture groups are retained post-transformation.

  • alphabet (str | unicode) – the name of the alphabet to use when this template is used for FPE encoding and decoding operations.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the create_or_update_template request.

Return type

requests.Response

create_or_update_transformation(name, transform_type, template, tweak_source='supplied', masking_character='*', allowed_roles=None, mount_point='transform')[source]

Create or update a transformation with the given name.

If a transformation with the name does not exist, it will be created. If the transformation exists, it will be updated with the new attributes.

Supported methods:

POST: /{mount_point}/transformation/:name.

Parameters
  • name (str | unicode) – the name of the transformation to create or update. This is part of the request URL.

  • transform_type (str | unicode) – Specifies the type of transformation to perform. The types currently supported by this backend are fpe and masking. This value cannot be modified by an update operation after creation.

  • template (str | unicode) – the template name to use for matching value on encode and decode operations when using this transformation.

  • tweak_source (str | unicode) – Only used when the type is FPE.

  • masking_character (str | unicode) – the character to use for masking. If multiple characters are provided, only the first one is used and the rest is ignored. Only used when the type is masking.

  • allowed_roles (list) – a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list in order for encode and decode operations to properly function.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the create_or_update_ation request.

Return type

requests.Response

decode(role_name, value=None, transformation=None, tweak=None, batch_input=None, mount_point='transform')[source]

Decode the provided value using a named role.

Supported methods:

POST: /{mount_point}/decode/:role_name.

Parameters
  • role_name (str | unicode) – the role name to use for this operation. This is specified as part of the URL.

  • value (str | unicode) – the value to be decoded.

  • transformation (str | unicode) – the transformation within the role that should be used for this decode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.

  • tweak (str | unicode) – the tweak source.

  • batch_input (array<object>) – a list of items to be decoded in a single batch. When this parameter is set, the ‘value’, ‘transformation’ and ‘tweak’ parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the decode request.

Return type

requests.Response

delete_alphabet(name, mount_point='transform')[source]

Delete an existing alphabet by the given name.

Supported methods:

DELETE: /{mount_point}/alphabet/:name.

Parameters
  • name (str | unicode) – the name of the alphabet to delete. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the delete_alphabet request.

Return type

requests.Response

delete_role(name, mount_point='transform')[source]

Delete an existing role by the given name.

Supported methods:

DELETE: /{mount_point}/role/:name.

Parameters
  • name (str | unicode) – the name of the role to delete. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the delete_role request.

Return type

requests.Response

delete_template(name, mount_point='transform')[source]

Delete an existing template by the given name.

Supported methods:

DELETE: /{mount_point}/template/:name.

Parameters
  • name (str | unicode) – the name of the template to delete. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the delete_template request.

Return type

requests.Response

delete_transformation(name, mount_point='transform')[source]

Delete an existing transformation by the given name.

Supported methods:

DELETE: /{mount_point}/transformation/:name.

Parameters
  • name (str | unicode) – the name of the transformation to delete. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the delete_ation request.

Return type

requests.Response

encode(role_name, value=None, transformation=None, tweak=None, batch_input=None, mount_point='transform')[source]

Encode the provided value using a named role.

Supported methods:

POST: /{mount_point}/encode/:role_name.

Parameters
  • role_name (str | unicode) – the role name to use for this operation. This is specified as part of the URL.

  • value (str | unicode) – the value to be encoded.

  • transformation (str | unicode) – the transformation within the role that should be used for this encode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.

  • tweak (str | unicode) – the tweak source.

  • batch_input (list) – a list of items to be encoded in a single batch. When this parameter is set, the ‘value’, ‘transformation’ and ‘tweak’ parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the encode request.

Return type

requests.Response

list_alphabets(mount_point='transform')[source]

List all existing alphabets in the secrets engine.

Supported methods:

LIST: /{mount_point}/alphabet.

Parameters

mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the list_alphabets request.

Return type

requests.Response

list_roles(mount_point='transform')[source]

List all existing roles in the secrets engine.

Supported methods:

LIST: /{mount_point}/role.

Parameters

mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the list_roles request.

Return type

requests.Response

list_templates(mount_point='transform')[source]

List all existing templates in the secrets engine.

Supported methods:

LIST: /{mount_point}/transformation.

Parameters

mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the list_template request.

Return type

requests.Response

list_transformations(mount_point='transform')[source]

List all existing transformations in the secrets engine.

Supported methods:

LIST: /{mount_point}/transformation.

Parameters

mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the list_ation request.

Return type

requests.Response

read_alphabet(name, mount_point='transform')[source]

Queries an existing alphabet by the given name.

Supported methods:

GET: /{mount_point}/alphabet/:name.

Parameters
  • name (str | unicode) – the name of the alphabet to delete. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the read_alphabet request.

Return type

requests.Response

read_role(name, mount_point='transform')[source]

Query an existing role by the given name.

Supported methods:

GET: /{mount_point}/role/:name.

Parameters
  • name (str | unicode) – the name of the role to read. This is part of the request URL.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the read_role request.

Return type

requests.Response

read_template(name, mount_point='transform')[source]

Query an existing template by the given name.

Supported methods:

GET: /{mount_point}/template/:name.

Parameters
  • name (str | unicode) – Specifies the name of the role to read.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the read_template request.

Return type

requests.Response

read_transformation(name, mount_point='transform')[source]

Query an existing transformation by the given name.

Supported methods:

GET: /{mount_point}/transformation/:name.

Parameters
  • name (str | unicode) – Specifies the name of the role to read.

  • mount_point (str | unicode) – The “path” the secrets engine was mounted on.

Returns

The response of the read_ation request.

Return type

requests.Response

class hvac.api.secrets_engines.Transit(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Transit Secrets Engine (API).

Reference: https://www.vaultproject.io/api/secret/transit/index.html

Methods

backup_key(name[, mount_point])

Return a plaintext backup of a named key.

create_key(name[, convergent_encryption, …])

Create a new named encryption key of the specified type.

decrypt_data(name, ciphertext[, context, …])

Decrypt the provided ciphertext using the named key.

delete_key(name[, mount_point])

Delete a named encryption key.

encrypt_data(name, plaintext[, context, …])

Encrypt the provided plaintext using the named key.

export_key(name, key_type[, version, …])

Return the named key.

generate_data_key(name, key_type[, context, …])

Generates a new high-entropy key and the value encrypted with the named key.

generate_hmac(name, hash_input[, …])

Return the digest of given data using the specified hash algorithm and the named key.

generate_random_bytes([n_bytes, …])

Return high-quality random bytes of the specified length.

hash_data(hash_input[, algorithm, …])

Return the cryptographic hash of given data using the specified algorithm.

list_keys([mount_point])

List keys (if there are any).

read_key(name[, mount_point])

Read information about a named encryption key.

restore_key(backup[, name, force, mount_point])

Restore the backup as a named key.

rewrap_data(name, ciphertext[, context, …])

Rewrap the provided ciphertext using the latest version of the named key.

rotate_key(name[, mount_point])

Rotate the version of the named key.

sign_data(name, hash_input[, key_version, …])

Return the cryptographic signature of the given data using the named key and the specified hash algorithm.

trim_key(name, min_version[, mount_point])

Trims older key versions setting a minimum version for the keyring.

update_key_configuration(name[, …])

Tune configuration values for a given key.

verify_signed_data(name, hash_input[, …])

Return whether the provided signature is valid for the given data.

backup_key(name, mount_point='transit')[source]

Return a plaintext backup of a named key.

The backup contains all the configuration data and keys of all the versions along with the HMAC key. The response from this endpoint can be used with the /restore endpoint to restore the key.

Supported methods:

GET: /{mount_point}/backup/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Name of the key.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

create_key(name, convergent_encryption=None, derived=None, exportable=None, allow_plaintext_backup=None, key_type=None, mount_point='transit')[source]

Create a new named encryption key of the specified type.

The values set here cannot be changed after key creation.

Supported methods:

POST: /{mount_point}/keys/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to create. This is specified as part of the URL.

  • convergent_encryption (bool) – If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. This requires derived to be set to true. When enabled, each encryption(/decryption/rewrap/datakey) operation will derive a nonce value rather than randomly generate it.

  • derived (bool) – Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation.

  • exportable (bool) – Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.

  • allow_plaintext_backup (bool) – If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.

  • key_type (str | unicode) –

    Specifies the type of key to create. The currently-supported types are:

    • aes256-gcm96: AES-256 wrapped with GCM using a 96-bit nonce size AEAD

    • chacha20-poly1305: ChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)

    • ed25519: ED25519 (asymmetric, supports derivation).

    • ecdsa-p256: ECDSA using the P-256 elliptic curve (asymmetric)

    • ecdsa-p384: ECDSA using the P-384 elliptic curve (asymmetric)

    • ecdsa-p521: ECDSA using the P-521 elliptic curve (asymmetric)

    • rsa-2048: RSA with bit size of 2048 (asymmetric)

    • rsa-3072: RSA with bit size of 3072 (asymmetric)

    • rsa-4096: RSA with bit size of 4096 (asymmetric)

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

decrypt_data(name, ciphertext, context=None, nonce=None, batch_input=None, mount_point='transit')[source]

Decrypt the provided ciphertext using the named key.

Supported methods:

POST: /{mount_point}/decrypt/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to decrypt against. This is specified as part of the URL.

  • ciphertext (str | unicode) – the ciphertext to decrypt.

  • context (str | unicode) – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.

  • nonce (str | unicode) – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+.

  • batch_input (List[dict]) – Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters ‘ciphertext’, ‘context’ and ‘nonce’ are also set, they will be ignored. Format for the input goes like this: [dict(context=”b64_context”, ciphertext=”b64_plaintext”), …]

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

delete_key(name, mount_point='transit')[source]

Delete a named encryption key.

It will no longer be possible to decrypt any data encrypted with the named key. Because this is a potentially catastrophic operation, the deletion_allowed tunable must be set in the key’s /config endpoint.

Supported methods:

DELETE: /{mount_point}/keys/{name}. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to delete. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

encrypt_data(name, plaintext, context=None, key_version=None, nonce=None, batch_input=None, type=None, convergent_encryption=None, mount_point='transit')[source]

Encrypt the provided plaintext using the named key.

This path supports the create and update policy capabilities as follows: if the user has the create capability for this endpoint in their policies, and the key does not exist, it will be upserted with default values (whether the key requires derivation depends on whether the context parameter is empty or not). If the user only has update capability and the key does not exist, an error will be returned.

Supported methods:

POST: /{mount_point}/encrypt/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to encrypt against. This is specified as part of the URL.

  • plaintext (str | unicode) – Specifies base64 encoded plaintext to be encoded.

  • context (str | unicode) – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled for this key.

  • key_version (int) – Specifies the version of the key to use for encryption. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.

  • nonce (str | unicode) – Specifies the base64 encoded nonce value. This must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.

  • batch_input (List[dict]) – Specifies a list of items to be encrypted in a single batch. When this parameter is set, if the parameters ‘plaintext’, ‘context’ and ‘nonce’ are also set, they will be ignored. The format for the input is: [dict(context=”b64_context”, plaintext=”b64_plaintext”), …]

  • type (str | unicode) – This parameter is required when encryption key is expected to be created. When performing an upsert operation, the type of key to create.

  • convergent_encryption (str | unicode) – This parameter will only be used when a key is expected to be created. Whether to support convergent encryption. This is only supported when using a key with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly generated nonce. As a result, when the same context and nonce are supplied, the same ciphertext is generated. It is very important when using this mode that you ensure that all nonces are unique for a given context. Failing to do so will severely impact the ciphertext’s security.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

export_key(name, key_type, version=None, mount_point='transit')[source]

Return the named key.

The keys object shows the value of the key for each version. If version is specified, the specific version will be returned. If latest is provided as the version, the current key will be provided. Depending on the type of key, different information may be returned. The key must be exportable to support this operation and the version must still be valid.

Supported methods:

GET: /{mount_point}/export/{key_type}/{name}(/{version}). Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the key to read information about. This is specified as part of the URL.

  • key_type (str | unicode) – Specifies the type of the key to export. This is specified as part of the URL. Valid values are: encryption-key signing-key hmac-key

  • version (str | unicode) – Specifies the version of the key to read. If omitted, all versions of the key will be returned. If the version is set to latest, the current key will be returned.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

generate_data_key(name, key_type, context=None, nonce=None, bits=None, mount_point='transit')[source]

Generates a new high-entropy key and the value encrypted with the named key.

Optionally return the plaintext of the key as well. Whether plaintext is returned depends on the path; as a result, you can use Vault ACL policies to control whether a user is allowed to retrieve the plaintext value of a key. This is useful if you want an untrusted user or operation to generate keys that are then made available to trusted users.

Supported methods:

POST: /{mount_point}/datakey/{key_type}/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to use to encrypt the datakey. This is specified as part of the URL.

  • key_type (str | unicode) – Specifies the type of key to generate. If plaintext, the plaintext key will be returned along with the ciphertext. If wrapped, only the ciphertext value will be returned. This is specified as part of the URL.

  • context (str | unicode) – Specifies the key derivation context, provided as a base64-encoded string. This must be provided if derivation is enabled.

  • nonce (str | unicode) – Specifies a nonce value, provided as base64 encoded. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.

  • bits (int) – Specifies the number of bits in the desired key. Can be 128, 256, or 512.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

generate_hmac(name, hash_input, key_version=None, algorithm=None, mount_point='transit')[source]

Return the digest of given data using the specified hash algorithm and the named key.

The key can be of any type supported by transit; the raw key will be marshaled into bytes to be used for the HMAC function. If the key is of a type that supports rotation, the latest (current) version will be used.

Supported methods:

POST: /{mount_point}/hmac/{name}(/{algorithm}). Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to generate hmac against. This is specified as part of the URL.

  • hash_input – Specifies the base64 encoded input data.

  • key_version (int) – Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.

  • algorithm (str | unicode) – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

generate_random_bytes(n_bytes=None, output_format=None, mount_point='transit')[source]

Return high-quality random bytes of the specified length.

Supported methods:

POST: /{mount_point}/random(/{bytes}). Produces: 200 application/json

Parameters
  • n_bytes (int) – Specifies the number of bytes to return. This value can be specified either in the request body, or as a part of the URL.

  • output_format (str | unicode) – Specifies the output encoding. Valid options are hex or base64.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

hash_data(hash_input, algorithm=None, output_format=None, mount_point='transit')[source]

Return the cryptographic hash of given data using the specified algorithm.

Supported methods:

POST: /{mount_point}/hash(/{algorithm}). Produces: 200 application/json

Parameters
  • hash_input (str | unicode) – Specifies the base64 encoded input data.

  • algorithm (str | unicode) – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512

  • output_format (str | unicode) – Specifies the output encoding. This can be either hex or base64.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

list_keys(mount_point='transit')[source]

List keys (if there are any).

Only the key names are returned (not the actual keys themselves).

An exception is thrown if there are no keys.

Supported methods:

LIST: /{mount_point}/keys. Produces: 200 application/json

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_key(name, mount_point='transit')[source]

Read information about a named encryption key.

The keys object shows the creation time of each key version; the values are not the keys themselves. Depending on the type of key, different information may be returned, e.g. an asymmetric key will return its public key in a standard format for the type.

Supported methods:

GET: /{mount_point}/keys/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to read. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the read_key request.

Return type

dict

restore_key(backup, name=None, force=None, mount_point='transit')[source]

Restore the backup as a named key.

This will restore the key configurations and all the versions of the named key along with HMAC keys. The input to this endpoint should be the output of /backup endpoint. For safety, by default the backend will refuse to restore to an existing key. If you want to reuse a key name, it is recommended you delete the key before restoring. It is a good idea to attempt restoring to a different key name first to verify that the operation successfully completes.

Supported methods:

POST: /{mount_point}/restore(/name). Produces: 204 (empty body)

Parameters
  • backup (str | unicode) – Backed up key data to be restored. This should be the output from the /backup endpoint.

  • name (str | unicode) – If set, this will be the name of the restored key.

  • force (bool) – If set, force the restore to proceed even if a key by this name already exists.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

rewrap_data(name, ciphertext, context=None, key_version=None, nonce=None, batch_input=None, mount_point='transit')[source]

Rewrap the provided ciphertext using the latest version of the named key.

Because this never returns plaintext, it is possible to delegate this functionality to untrusted users or scripts.

Supported methods:

POST: /{mount_point}/rewrap/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to re-encrypt against. This is specified as part of the URL.

  • ciphertext (str | unicode) – Specifies the ciphertext to re-encrypt.

  • context (str | unicode) – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.

  • key_version (int) – Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.

  • nonce (str | unicode) – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+.

  • batch_input (List[dict]) – Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters ‘ciphertext’, ‘context’ and ‘nonce’ are also set, they will be ignored. Format for the input goes like this: [dict(context=”b64_context”, ciphertext=”b64_plaintext”), …]

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

rotate_key(name, mount_point='transit')[source]

Rotate the version of the named key.

After rotation, new plaintext requests will be encrypted with the new version of the key. To upgrade ciphertext to be encrypted with the latest version of the key, use the rewrap endpoint. This is only supported with keys that support encryption and decryption operations.

Supported methods:

POST: /{mount_point}/keys/{name}/rotate. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Specifies the name of the key to read information about. This is specified as part of the URL.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

sign_data(name, hash_input, key_version=None, hash_algorithm=None, context=None, prehashed=None, signature_algorithm=None, marshaling_algorithm=None, mount_point='transit')[source]

Return the cryptographic signature of the given data using the named key and the specified hash algorithm.

The key must be of a type that supports signing.

Supported methods:

POST: /{mount_point}/sign/{name}(/{hash_algorithm}). Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to use for signing. This is specified as part of the URL.

  • hash_input (str | unicode) – Specifies the base64 encoded input data.

  • key_version (int) – Specifies the version of the key to use for signing. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.

  • hash_algorithm (str | unicode) – Specifies the hash algorithm to use for supporting key types (notably, not including ed25519 which specifies its own hash algorithm). This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512

  • context (str | unicode) – Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.

  • prehashed (bool) – Set to true when the input is already hashed. If the key type is rsa-2048 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter. Just as the value to sign should be the base64-encoded representation of the exact binary data you want signed, when set, input is expected to be base64-encoded binary hashed data, not hex-formatted. (As an example, on the command line, you could generate a suitable input via openssl dgst -sha256 -binary | base64.)

  • signature_algorithm (str | unicode) – When using a RSA key, specifies the RSA signature algorithm to use for signing. Supported signature types are: pss, pkcs1v15

  • marshaling_algorithm (str | unicode) – Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. Supported types are: asn1, jws

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict

trim_key(name, min_version, mount_point='transit')[source]

Trims older key versions setting a minimum version for the keyring.

Once trimmed, previous versions of the key cannot be recovered.

Supported methods:

POST: /{mount_point}/keys/{name}/trim. Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the key to be trimmed.

  • min_version (int) – The minimum version for the key ring. All versions before this version will be permanently deleted. This value can at most be equal to the lesser of min_decryption_version and min_encryption_version. This is not allowed to be set when either min_encryption_version or min_decryption_version is set to zero.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

dict

update_key_configuration(name, min_decryption_version=None, min_encryption_version=None, deletion_allowed=None, exportable=None, allow_plaintext_backup=None, mount_point='transit')[source]

Tune configuration values for a given key.

These values are returned during a read operation on the named key.

Supported methods:

POST: /{mount_point}/keys/{name}/config. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – Specifies the name of the encryption key to update configuration for.

  • min_decryption_version (int) – Specifies the minimum version of ciphertext allowed to be decrypted. Adjusting this as part of a key rotation policy can prevent old copies of ciphertext from being decrypted, should they fall into the wrong hands. For signatures, this value controls the minimum version of signature that can be verified against. For HMACs, this controls the minimum version of a key allowed to be used as the key for verification.

  • min_encryption_version (int) – Specifies the minimum version of the key that can be used to encrypt plaintext, sign payloads, or generate HMACs. Must be 0 (which will use the latest version) or a value greater or equal to min_decryption_version.

  • deletion_allowed (bool) – Specifies if the key is allowed to be deleted.

  • exportable (bool) – Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.

  • allow_plaintext_backup (bool) – If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

verify_signed_data(name, hash_input, signature=None, hmac=None, hash_algorithm=None, context=None, prehashed=None, signature_algorithm=None, marshaling_algorithm=None, mount_point='transit')[source]

Return whether the provided signature is valid for the given data.

Supported methods:

POST: /{mount_point}/verify/{name}(/{hash_algorithm}). Produces: 200 application/json

Parameters
  • name (str | unicode) – Specifies the name of the encryption key that was used to generate the signature or HMAC.

  • hash_input – Specifies the base64 encoded input data.

  • signature (str | unicode) – Specifies the signature output from the /transit/sign function. Either this must be supplied or hmac must be supplied.

  • hmac (str | unicode) – Specifies the signature output from the /transit/hmac function. Either this must be supplied or signature must be supplied.

  • hash_algorithm (str | unicode) – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512

  • context (str | unicode) – Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.

  • prehashed (bool) – Set to true when the input is already hashed. If the key type is rsa-2048 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter.

  • signature_algorithm (str | unicode) – When using a RSA key, specifies the RSA signature algorithm to use for signature verification. Supported signature types are: pss, pkcs1v15

  • marshaling_algorithm (str | unicode) – Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. Supported types are: asn1, jws

  • mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the request.

Return type

dict