Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

ActionEffect
Expire nowBouncer 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 expiryBouncer 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
ReplaceBouncer 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:

OperationConfigured resourcePersonal credential
List version history, without valuesIts approversIts owner and people it is shared with
Expire, schedule or remove a scheduled expiryIts approversIts owner, Editors and Managers
ReplaceIts approvers, with allow_write: true and self_approval: trueIts owner, Editors and Managers
View an old version's valueIts approvers, with view enabledOwner 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

  1. 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.
  2. 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.
  3. Check the KV mount's and the secret's max_versions, and any delete_version_after setting, 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.
  4. Decide who should be able to expire values and inspect old ones using the table above. Enabling lifecycle on a resource with view enabled also gives its approvers the separate old-value view, and a reload records this as a policy_loosened entry 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.

  1. In the role kit's resources file, add lifecycle to the resource's line. For the example in step 3, the line is:

    example-api-key  kv  apps/example/api-key  lifecycle
    

    The lifecycle word 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. The write and view words control their own data permissions.

  2. 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.

  3. Add lifecycle: true to 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 write on the role-kit line, allow_write: true and self_approval: true. Self-approval also lets Alice approve her own access requests, so review that policy separately. App viewing needs view in both places. See Resources and policy.

  4. For an existing resource, reload from your Compose folder:

    docker compose exec bouncer bouncer-admin config reload
    

    A new resource needs a server restart instead.

  5. Check the reload succeeded, then read the approval log for any policy_loosened entries. 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 1h if 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.

  1. Add lifecycle to the namespace's line in the role kit:

    personal  kv  bouncer-personal  personal lifecycle
    
  2. Apply and check the role kit, as for a resource above.

  3. Add lifecycle: true to 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
    
  4. 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.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).