Lease

View and Manage Leases

Read a lease:

>>> read_lease_response = client.sys.read_lease(lease_id=lease_id)
>>> print('Expire time for lease ID {id} is: {expire_time}'.format(
...     id=lease_id,
...     expire_time=read_lease_response['data']['expire_time'],
... ))
Expire time for lease ID pki/issue/my-role/... is: 20...

Renewing a lease:

>>> renew_lease_resp = client.sys.renew_lease(lease_id=lease_id)
>>> print('Lease ID: "{id}" renewed, lease duration: "{duration}"'.format(
...     id=renew_lease_resp['lease_id'],
...     duration=renew_lease_resp['lease_duration'],
... ))
Lease ID: "pki/issue/my-role/d05138a2-edeb-889d-db98-2057ecd5138f" renewed, lease duration: "2764790"

Revoking a lease:

>>> client.sys.revoke_lease(lease_id=lease_id)
<Response [204]>

Read Lease

Lease.read_lease(lease_id)[source]

Retrieve lease metadata.

Supported methods:

PUT: /sys/leases/lookup. Produces: 200 application/json

Parameters:

lease_id (str | unicode) – the ID of the lease to lookup.

Returns:

Parsed JSON response from the leases PUT request

Return type:

dict.

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

read_lease_resp = client.sys.read_lease(
    lease_id=lease_id,
)

# expire_time in the form of something like: 2019-02-25T07:41:30.000038-06:00
print('Current expire time for lease ID {id} is: {expires}'.format(
    id=lease_id,
    expires=read_lease_resp['data']['expire_time'],
))

Example output:

Current expire time for lease ID pki/issue/my-role/... is: ...

List Leases

Lease.list_leases(prefix)[source]

Retrieve a list of lease ids.

Supported methods:

LIST: /sys/leases/lookup/{prefix}. Produces: 200 application/json

Parameters:

prefix (str | unicode) – Lease prefix to filter list by.

Returns:

The JSON response of the request.

Return type:

dict

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

list_leases_response = client.sys.list_leases(
    prefix='pki',
)
print('The follow lease keys are active under the "pki" prefix: %s' % list_leases_response['data']['keys'])

Example output:

The follow lease keys are active under the "pki" prefix: ['issue/']

Renew Lease

Lease.renew_lease(lease_id, increment=None)[source]

Renew a lease, requesting to extend the lease.

Supported methods:

PUT: /sys/leases/renew. Produces: 200 application/json

Parameters:

  • lease_id (str | unicode) – The ID of the lease to extend.

  • increment (int) – The requested amount of time (in seconds) to extend the lease.

Returns:

The JSON response of the request

Return type:

dict

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

client.sys.renew_lease(
    lease_id=lease_id,
    increment=500,
)

Revoke Lease

Lease.revoke_lease(lease_id)[source]

Revoke a lease immediately.

Supported methods:

PUT: /sys/leases/revoke. Produces: 204 (empty body)

Parameters:

lease_id (str | unicode) – Specifies the ID of the lease to revoke.

Returns:

The response of the request.

Return type:

requests.Response

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

client.sys.revoke_lease(
    lease_id=lease_id,
)

Revoke Prefix

Lease.revoke_prefix(prefix)[source]

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

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

Supported methods:

PUT: /sys/leases/revoke-prefix/{prefix}. Produces: 204 (empty body)

Parameters:

prefix (str | unicode) – The prefix to revoke.

Returns:

The response of the request.

Return type:

requests.Response

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

client.sys.revoke_prefix(
    prefix='pki',
)

Revoke Force

Lease.revoke_force(prefix)[source]

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

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

Supported methods:

PUT: /sys/leases/revoke-force/{prefix}. Produces: 204 (empty body)

Parameters:

prefix (str | unicode) – The prefix to revoke.

Returns:

The response of the request.

Return type:

requests.Response

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

client.sys.revoke_force(
    prefix='pki',
)