Credential expiry, replacement and history
Credential lifecycle (the lifecycle setting) lets a person expire a stored
value, now or on a schedule, and save a replacement under the same
credential. The credential's ID, name, folder, owner, sharing and the
reference that scripts and agents use to fetch it stay the same; only the
value changes. Each save creates a new version of the secret at the same
path in OpenBao's KV version 2 store.
It is off by default, and the operator chooses whether to enable it for a resource or a personal storage area. Lifecycle first appeared in 0.5.3. The device-key checks here need Bouncer 0.5.7 on both the server and the app. For source builds, record the commit used to build each component. For a server built with the Compose kit's default image name, check its revision label after building the image:
docker image inspect localhost/bouncer-server:local \
--format '{{index .Config.Labels "org.opencontainers.image.revision"}}'
Use your own image name if you changed it. Compare the label with the
source commit you chose to build. The /v1/health
version string alone could not identify these changes in the earlier tests:
source builds tested before the 0.5.7 version bump still reported
0.5.6+33. Check
Platforms and status and the
upgrade instructions before changing configuration.
Verification on 18 November 2026: these procedures were run with fake data, through the server's API and operator commands, against a server built from source after 0.5.6. Steps changed after that run were run again. App screens, real hardware keys, downstream sessions and rollback to a server without lifecycle support weren't run.
What expiry and replacement change
| Action | Effect |
|---|---|
| Expire now | Bouncer stops handing out the current value and tries to revoke the OpenBao tokens it issued for it, including unused wrapping tokens. A wrapping token lets the requester collect a response from OpenBao once; for a personal credential, that response holds the value. Failed revocations are recorded and retried. The app reporting the expiry doesn't mean every revoke at OpenBao has succeeded |
| Schedule expiry | Bouncer stops handing out the value at the scheduled time, even if its background task runs late. New tokens are issued to end no later than that time. Bouncer tries to revoke tokens issued before the schedule was set when it processes the expiry, and an outage can delay those revocations |
| Replace | Bouncer saves a new version only if the version the person saw is still current. Existing grants can use the replacement; they belong to the credential, not a version |
Replacing a configured resource does not revoke the OpenBao tokens already issued for it. While a token is still valid, it can read the replacement. Replacing a personal credential tries to revoke its unused wrapping tokens, because the responses they hold could still contain the old value. Neither recalls a value someone has already read.
An expired current value stays unavailable until it is replaced. Bouncer never supplies an older value instead. When lifecycle is on, Bouncer also refuses retrieval if it can't read OpenBao's version metadata.
Expiry does not delete a value. OpenBao keeps the values encrypted in its version history; Bouncer's database keeps version numbers, who made each change, and when. The server handles plaintext during replacement and authorised viewing, as it does for other app saves and views.
A copied password or API key still works at its issuer until it is rotated or revoked there. Expiry and replacement do not close an existing SSH, database or application session. Keep these apart: a grant's end time, a standing grant's review date, a version's scheduled expiry, and a downstream credential being marked rotated are separate things. Keep standing access disabled; enabling lifecycle does not resolve its open policy questions.
Who may do what
These permissions apply while lifecycle is on:
| Operation | Configured resource | Personal credential |
|---|---|---|
| List version history, without values | Its approvers | Its owner and people it is shared with |
| Expire, schedule or remove a scheduled expiry | Its approvers | Its owner, Editors and Managers |
| Replace | Its approvers, with allow_write: true and self_approval: true | Its owner, Editors and Managers |
| View an old version's value | Its approvers, with view enabled | Owner only, where the namespace permits reveal |
Expiring, scheduling, replacing or viewing an old value needs a paired device whose key checks it's you on every use (user verification): a biometric phone key or Windows Hello. The server also applies the resource's key settings. Windows Hello alone does not prove hardware attestation or satisfy every resource policy. See Device keys and user verification.
Viewing an old value is signed and logged separately; it is for authorised
inspection, not a fallback for normal use. Requester keys, the CLI and MCP
cannot manage lifecycle or view old versions. There are no bouncer-admin
commands for history, expiry, scheduling or replacement yet.
Before enabling it
- Check the server and app source commits, and take the usual backups. Make sure you can still administer and recover OpenBao without the credential you're changing.
- Use the role kit from 0.5.5 or later, with its upgrade handling for earlier policies. Follow the kit upgrade instructions in the release or repository; do not copy new scripts over an old kit's files and assume the upgrade is complete.
- Check the KV mount's and the secret's
max_versions, and anydelete_version_aftersetting, with your OpenBao administrator. Bouncer refuses a save that would make OpenBao permanently remove (prune) an old version. It can't stop an OpenBao administrator, or an automatic deletion setting, from removing values. - Decide who should be able to expire values and inspect old ones using
the table above. Enabling lifecycle on a resource with
viewenabled also gives its approvers the separate old-value view, and a reload records this as apolicy_loosenedentry in the approval log.
Enable a configured resource
Use this for a stored secret or API key resource with exactly one kv
entry. SSH host resources don't have this option. Upgrade the role kit
before you turn lifecycle on in Bouncer.
-
In the role kit's
resourcesfile, addlifecycleto the resource's line. For the example in step 3, the line is:example-api-key kv apps/example/api-key lifecycleThe
lifecycleword grants the server read access to the secret's version metadata and the mount's settings. It does not grant a value read, metadata changes or deletion. Thewriteandviewwords control their own data permissions. -
Apply and check the role kit as in Install, step 2, including its permission check. Its resource token policies must deny reads that specify
version, so requesters can't bypass current-only retrieval. -
Add
lifecycle: trueto the resource. This example is a resource section to merge into your existing configuration. It permits expiry and history, with app saves, app viewing and self-approval off:resources: - id: example-api-key name: Example API key kind: stored_api_key kv: - mount: kv path: apps/example/api-key fields: [api_key] approvers: [alice] requesters: [alice] lifecycle: true allow_write: false self_approval: false view: "off"If you choose to allow replacement from the app, it also needs
writeon the role-kit line,allow_write: trueandself_approval: true. Self-approval also lets Alice approve her own access requests, so review that policy separately. App viewing needsviewin both places. See Resources and policy. -
For an existing resource, reload from your Compose folder:
docker compose exec bouncer bouncer-admin config reloadA new resource needs a server restart instead.
-
Check the reload succeeded, then read the approval log for any
policy_loosenedentries. The reload output does not show them. From your Compose folder, this exports the last hour and filters those entries:docker compose exec -T bouncer bouncer-admin log export --since 1h \ | jq -c 'select(.kind == "policy_loosened")'Match the entry's time and config revision to your reload. Change
1hif you need a longer period. You can also read the affected person's app History; Audit explains full exports.
To verify, open the credential's Details on an authorised paired app and check that Versions appears. Use fake data to check expiry and refusal of retrieval before relying on the procedure. Check replacement too if you separately choose to permit it.
Enable a personal storage area
A personal storage area is a personal_credentials namespace in the
configuration. The setting applies to every credential in it.
-
Add
lifecycleto the namespace's line in the role kit:personal kv bouncer-personal personal lifecycle -
Apply and check the role kit, as for a resource above.
-
Add
lifecycle: trueto the namespace. This example keeps reveal and automatic approval off:personal_credentials: - id: personal label: Personal credentials kv: {mount: kv, prefix: bouncer-personal} creators: [alice] lifecycle: true ceilings: credential_ttl: 5m durations: presets: [5m, 15m, 1h] min: 1m max: 1h always: false reveal: false always_approved: false -
Reload Bouncer, as above.
Existing values stay at their paths. An old save that Bouncer did not record shows as "Saved (date) outside Bouncer" when OpenBao supplies its creation time, or "Saved before Bouncer kept its history" when no date is available. To verify, check a newly created fake credential and an existing one, including what a shared Viewer and Editor can do. The app's version instructions cover expiry and replacement.
Retention and refused replacements
Bouncer never deletes or destroys an OpenBao version or changes retention settings, and there is no way to confirm pruning an old value. There is no Bouncer retention setting or pruning command. A way to prune deliberately has been proposed but not built.
In OpenBao 2.7.2, the version we checked, the number of versions kept is the
larger of the secret's and the mount's max_versions, or 10 when neither is
set. Lowering a secret's limit below its mount's doesn't make it smaller.
At that limit, Bouncer refuses the next save rather than let OpenBao remove
an old value. Before a replacement can succeed, review and raise the
OpenBao limit that applies. Keep the retained values and their backups
protected as secrets.
Other refused replacements:
- If someone else changed the current version first, the replacement is refused. Reopen the credential and check the new current version before retrying.
- If Bouncer reports that OpenBao's answer was lost, the save may have happened. Check Versions before retrying. A successful but unrecorded save shows as "Saved (date) outside Bouncer", without an author. For a personal credential, this failed response also means the replacement did not revoke its unused wrapping tokens, which may still hold the old value.
- If the current version was deleted (but not destroyed) in OpenBao, Bouncer can't replace it. An OpenBao administrator must resolve that first.
Don't use an old value as a workaround.
Turn lifecycle off
Before turning it off, remove any scheduled expiries you no longer want.
Then set lifecycle: false on the resource or namespace and reload. This is
recorded as policy_loosened in the approval log; read it with the
export command above or in the affected person's app History. The app
no longer shows version history,
old-value viewing or version changes; new personal credentials in that
namespace get no lifecycle history.
Scheduled expiries still take effect. You cannot remove them from the
app while lifecycle is off. Recorded expiries still hold, and saves to
credentials that already have history are still refused if they would
prune an old value. Keep the role kit's lifecycle permission while those
credentials remain in use. Without it, Bouncer can't read their version
metadata, so retrieval and saves can fail. Turning the setting off doesn't
reset expiries and isn't a way round the retention limit.
If that permission has already been removed, put lifecycle back on the
role-kit line, apply and check the kit, then either enable lifecycle and
replace from the app, or leave it off and save a new value through Edit.
Do not remove database history rows to bypass an expiry.
Restore or roll back
A database restore loses expiries recorded after its backup. Before reopening access, use the approval log kept off the server to identify those versions, then expire them again or save replacements. Check the current version for each credential first. If the log does not cover the whole period, keep access closed until you have reconciled every value that may have been expired. Also follow the other restore reconciliation steps.
Before rolling back to a server without lifecycle support, replace every expired current version while the current server still runs. An older server does not enforce version expiry and could hand those values out again. Rotate external credentials at their issuer as needed, then save the new values; do not re-enter an expired value as its replacement. Turning lifecycle off does not provide this protection. Follow the rollback procedure as well.