Token TTL
How long the Vault authorization credential remains usable.
Chapter contract
Prerequisites:
Chapter 3 complete and the constrained learner token available.
User-visible outcome:
Priya can distinguish token and secret lease clocks and revoke a lease without displaying credentials.
Learning objectives
- Read token and lease metadata without secret values.
- Differentiate renewable, periodic, orphan, and batch token behavior.
- Design renewal and shutdown around failure before expiry.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
Secret lease TTL
How long generated material remains valid.
Renewal
An authenticated extension within configured limits.
Revocation
Invalidation of a token or lease and supported external credentials.
Commands and configuration
source learn-vault/.runtime/learner.env
vault token lookup -format=json | jq '{ttl:.data.ttl,renewable:.data.renewable}'
vault read -format=json database/creds/orders-api | jq '{lease_id_present:(.lease_id|length>0),lease_duration,renewable}'Secret-safety stop
Stop: Never infer validity from token prefix or length. Token strings are opaque; use lookup metadata and handle API failure.
Failure drill
| Symptom | Database requests fail although Vault login works. |
|---|---|
| Likely causes | The database lease expired, renewal stopped, or the pool retained revoked connections. |
| Inspect safely | Compare token TTL, lease duration, renewal timestamps, and pool errors. |
| Do not print | Token, leased username, password, or database URL. |
Break it / fix it
Break it: Revoke the database lease and attempt to reuse it.
Show diagnosis and fix
Fix it: Obtain replacement material and rebuild the consumer connection rather than extending revoked data.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Request a database lease into ignored storage, inspect metadata, revoke it, and remove the runtime response.
source learn-vault/.runtime/learner.env
umask 077
vault read -format=json database/creds/orders-api > learn-vault/.runtime/db-lease.json
jq '{lease_id_present:(.lease_id|length>0),lease_duration,renewable}' learn-vault/.runtime/db-lease.json
lease_id=$(jq -r '.lease_id' learn-vault/.runtime/db-lease.json)
vault lease revoke "$lease_id"
rm -f learn-vault/.runtime/db-lease.jsonSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- Lease metadata shows a finite duration and non-empty lease ID.
- Revocation succeeds without printing credentials.
- The runtime lease file is removed.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Remove runtime lease files and unset VAULT_TOKEN; Vault cleans the revoked database principal.
Project Lockbox increment
orders-api has two clocks: auth token and database lease. Readiness needs safe margin on both.
Quick check
Can a valid token guarantee a database lease?
No. Their TTLs and renewal outcomes are independent.
What can parent-token revocation affect?
Child tokens and leases, subject to token hierarchy semantics.
When should a consumer renew?
Before expiry, with jitter and enough retry margin.
What follows terminal renewal failure?
Obtain fresh identity and material or fail closed before expiry.
Gotchas
- Renewable does not mean renewable beyond max TTL.
- Revocation may not terminate an existing DB session immediately.
- Batch tokens do not support every service-token feature.
Recap and next
Treat each credential as a timed capability with a replacement path and an explicit stop-using deadline.