Vault
HomeDocumentationTutorialsTry Cloud!
  • Vault
  • Documentation
    • What is Vault?
    • Use Cases
    • Setup
      • Install
      • Configuration
    • Get Started
      • Starting the server
      • Your first secret
      • Deploying Vault on VMs with Let's encrypt! TLS certs
    • Concepts
      • Operations
        • Seal/Unseal
        • "Dev" server mode
        • Namespace lock and unlock
        • Lease, renew, and revoke
        • Lease Explosions
        • Mount migration
        • Client count
        • Resource quotas
        • Response wrapping
      • Authentication
        • Identity
        • Tokens
        • OIDC provider
        • Username templating
        • Passwordless
      • Secrets
      • Storage
        • Integrated storage
        • High availability mode (HA)
        • Recovery mode
      • Policies
  • Tutorials
    • CLI
      • Operations
        • Deploy Vault
        • Using the HTTP API
        • Unseal/Seal
      • Authentication
        • Token
        • GitHub authentication
        • Username/Password
        • TLS Client Certificates
        • SSH Keys
        • AWS, Azure, GCP and external auth methods
          • Azure
          • AWS
          • GCP
          • Github
          • Terraform
      • Secrets
        • Secrets engines
        • Built-in help
      • Access Control
        • Policies
    • UI
      • Authentication
        • Username/Password
        • Passwordless
      • Operations
        • Unseal / Seal
        • API Explorer
      • Secrets
        • Secrets engines
      • Access Control
        • Policies
    • Use Cases
      • Namespaces
      • MongoDB admin password
      • VM Disk Encryption Keys
      • VM SSH Keys
      • Kubernetes Configuration
      • GitHub Actions
      • Dynamic credentials for cloud providers
        • AWS
        • Azure
        • GCP
  • CLI
    • agent
    • audit
    • auth
    • debug
    • delete
    • events
    • kv
    • lease
    • license
    • list
    • login
    • monitor
    • namespace
    • operator
    • patch
    • path-help
    • pki
    • plugin
    • policy
    • print
    • proxy
    • read
    • secrets
    • server
    • ssh
    • status
    • token
    • transit
    • unwrap
    • version
    • version-history
    • write
  • API
    • Secrets engines
      • AliCloud secrets engine (API)
      • AWS secrets engine (API)
      • Azure secrets engine (API)
      • Cubbyhole secrets engine (API)
      • Database
        • Cassandra database plugin HTTP API
        • Elasticsearch database plugin HTTP API
        • Influxdb database plugin HTTP API
        • MongoDB database plugin HTTP API
        • MSSQL database plugin HTTP API
        • MySQL/MariaDB database plugin HTTP API
        • Oracle database plugin HTTP API
        • PostgreSQL database plugin HTTP API
        • Redis database plugin HTTP API
        • Redis ElastiCache database plugin HTTP API
        • Redshift database plugin HTTP API
        • Snowflake database plugin HTTP API
      • Google Cloud secrets engine (API)
      • Google Cloud KMS secrets engine (API)
      • Identity
        • entity
        • entity-alias
        • group
        • group-alias
        • tokens
        • lookup
        • oidc-provider
        • MFA
          • duo
          • okta
          • pingid
          • totp
          • login-enforcement
      • KV secrets engine (API)
      • Buckypaper secrets engine
      • Kubernetes secrets engine (API)
      • Nomad secrets engine (API)
      • LDAP secrets engine (API)
      • PKI secrets engine (API)
      • RabbitMQ secrets engine (API)
      • SSH secrets engine (API)
      • TOTP secrets engine (API)
      • Transit secrets engine (API)
    • Auth engines
      • AliCloud auth method (API)
      • AppRole auth method (API)
      • AWS auth method (API)
      • Azure auth method (API)
      • Pivotal Cloud Foundry (CF) auth method (API)
      • GitHub auth method (API)
      • Google Cloud auth method (API)
      • JWT/OIDC auth method (API)
      • Kerberos auth method (API)
      • Kubernetes auth method (API)
      • LDAP auth method (API)
      • OCI auth method (API)
      • Okta auth method (API)
      • Passwordless auth method (API)
      • RADIUS auth method (API)
      • TLS certificate auth method (API)
      • Token auth method (API)
      • Userpass auth method (HTTP API)
    • Service engines
      • Licence Manager
    • System backend
      • /sys/audit
      • /sys/audit-hash
      • /sys/auth
      • /sys/capabilities
      • /sys/capabilities-accessor
      • /sys/capabilities-self
      • /sys/config/auditing/request-headers
      • /sys/config/control-group
      • /sys/config/cors
      • /sys/config/reload
      • /sys/config/state
      • /sys/config/ui
      • /sys/decode-token
      • /sys/experiments
      • /sys/generate-recovery-token
      • /sys/generate-root
      • /sys/health
      • /sys/host-info
      • /sys/in-flight-req
      • /sys/init
      • /sys/internal/counters
      • /sys/internal/inspect
        • /sys/internal/inspect/router
      • /sys/internal/specs/openapi
      • /sys/internal/ui/feature-flags
      • /sys/internal/ui/mounts
      • /sys/internal/ui/namespaces
      • /sys/internal/ui/resultant-acl
      • /sys/key-status
      • /sys/ha-status
      • /sys/leader
      • /sys/leases
      • /sys/license/status
      • /sys/locked-users
      • /sys/loggers
      • /sys/metrics
      • /sys/monitor
      • /sys/mounts
      • /sys/namespaces
      • /sys/plugins/reload/backend
      • /sys/plugins/catalog
      • /sys/plugins/runtimes/catalog
      • /sys/policy
      • /sys/policies/
      • /sys/policies/password/
      • /sys/pprof
      • /sys/quotas/config
      • /sys/quotas/rate-limit
      • /sys/quotas/lease-count
      • /sys/raw
      • /sys/rekey
      • /sys/rekey-recovery-key
      • /sys/remount
      • /sys/rotate
      • /sys/rotate/config
      • /sys/seal
      • /sys/seal-status
      • /sys/seal-backend-status
      • /sys/step-down
      • /sys/storage
        • /sys/storage/raft
        • /sys/storage/raft/autopilot
      • /sys/tools
      • /sys/unseal
      • /sys/version-history
      • /sys/wrapping/lookup
      • /sys/wrapping/rewrap
      • /sys/wrapping/unwrap
      • /sys/wrapping/wrap
  • Resources
    • Blog
    • GitHub
    • Youtube
    • CCx101
Powered by GitBook
On this page
  • Read lease
  • List leases
  • Renew lease
  • Revoke lease
  • Revoke force
  • Revoke prefix
  • Tidy leases
  • Lease counts
  • Leases list
  1. API
  2. System backend

/sys/leases

The /sys/leases endpoints are used to view and manage leases in Vault.

Read lease

This endpoint retrieve lease metadata.

Method
Path

POST

/sys/leases/lookup

Parameters

  • lease_id (string: <required>) – Specifies the ID of the lease to lookup.

Sample payload

{
  "lease_id": "aws/creds/deploy/abcd-1234..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/leases/lookup

Sample response

{
  "id": "auth/token/create/25c75065466dfc5f920525feafe47502c4c9915c",
  "issue_time": "2017-04-30T10:18:11.228946471-04:00",
  "expire_time": "2017-04-30T11:18:11.228946708-04:00",
  "last_renewal_time": null,
  "renewable": true,
  "ttl": 3558
}

List leases

This endpoint returns a list of lease ids.

This endpoint requires 'sudo' capability.

Method
Path

LIST

/sys/leases/lookup/:prefix

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/leases/lookup/aws/creds/deploy/

Sample response

{
  "data": {
    "keys": ["abcd-1234...", "efgh-1234...", "ijkl-1234..."]
  }
}

Renew lease

This endpoint renews a lease, requesting to extend the lease. Token leases cannot be renewed using this endpoint, use instead the auth/token/renew endpoint.

Method
Path

POST

/sys/leases/renew

Parameters

  • lease_id (string: <required>) – Specifies the ID of the lease to extend. This parameter can either be specified in a json request, as shown below, or provided as a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are provided, the leaseID in the request json takes precedence.

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

Sample payload

{
  "lease_id": "aws/creds/deploy/abcd-1234...",
  "increment": 1800
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/leases/renew

Sample response

{
  "lease_id": "aws/creds/deploy/abcd-1234...",
  "renewable": true,
  "lease_duration": 2764790
}

Revoke lease

This endpoint revokes a lease immediately.

Method
Path

POST

/sys/leases/revoke

Parameters

  • lease_id (string: <required>) – Specifies the ID of the lease to revoke. This parameter can either be specified in a json request, as shown below, or provided as a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are provided, the leaseID in the request json takes precedence.

  • sync (bool: false) - Instead of the default behaviour of queueing the lease revocation, sync=true will revoke the lease immediately and only return once complete.

Sample payload

{
  "lease_id": "postgresql/creds/readonly/abcd-1234..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/leases/revoke

Revoke force

This endpoint revokes all secrets or tokens generated under a given prefix immediately. Unlike /sys/leases/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.

By ignoring these errors, Vault abdicates responsibility for ensuring that the issued credentials or secrets are properly revoked and/or cleaned up. Access to this endpoint should be tightly controlled.

This endpoint requires 'sudo' capability.

Method
Path

POST

/sys/leases/revoke-force/:prefix

Parameters

  • prefix (string: <required>) – Specifies the prefix to revoke. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/revoke-force/aws/creds

Revoke prefix

This endpoint revokes 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.

This endpoint requires 'sudo' capability.

Method
Path

POST

/sys/leases/revoke-prefix/:prefix

Parameters

  • prefix (string: <required>) – Specifies the prefix to revoke. This is specified as part of the URL.

  • sync (bool: false) - Instead of the default behaviour of queueing the lease revocations, sync=true will revoke ths leases immediately and only return once complete.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/aws/creds

Tidy leases

This endpoint cleans up the dangling storage entries for leases: for each lease entry in storage, Vault will verify that it has an associated valid non-expired token in storage, and if not, the lease will be revoked.

Generally, running this is not needed unless upgrade notes or support personnel suggest it. This may perform a lot of I/O to the storage method so should be used sparingly.

Method
Path

POST

/sys/leases/tidy

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/tidy

Lease counts

This endpoint returns the total count of a type of lease, as well as a count per mount point. Note that it currently only supports type "irrevocable".

This can help determine if particular endpoints are disproportionately resulting in irrevocable leases.

This endpoint was added in Vault 1.8.

Parameters

  • type (string: <required>) - Specifies the type of lease.

  • include_child_namespaces (bool: false) - Specifies if leases in child namespaces should be included in the result.

Method
Path

GET

/sys/leases/count

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/leases/count \
    -d type=irrevocable

Leases list

This endpoint returns the total count of a type of lease, as well as a list of leases per mount point. Note that it currently only supports type "irrevocable".

This can help determine if particular endpoints or causes are disproportionately resulting in irrevocable leases.

This endpoint was added in Vault 1.8.

Parameters

  • type (string: <required>) - Specifies the type of lease.

  • include_child_namespaces (bool: false) - Specifies if leases in child namespaces should be included in the result

  • limit (string: "") - Specifies the maximum number of leases to return in a request. To return all results, set to none. If not set, this API will return a maximum of 10,000 leases. If not set to none and there exist more leases than limit, the response will include a warning.

Method
Path

GET

/sys/leases

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/leases \
    -d type=irrevocable
Previous/sys/leaderNext/sys/license/status

Last updated 1 year ago