Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
Config file reference
Every setting in bouncer.yaml, as the config loader reads it in the source this site was built from. Settings that 0.5.6 and earlier refuse are marked "from 0.5.7". Configure the server explains how to use them. The repository's contracts/config/bouncer.example.yaml is a commented example with every section, and contracts/schemas/config.v1.json is the JSON Schema.
General rules:
- Unknown keys are refused, and so are repeated keys. A typo is an error, not ignored.
- Durations are a whole number and a unit:
s,m,hord(90s,15m,6h,7d). - Booleans are only
trueorfalse. - The file holds no secrets: only the paths of files that do.
Top level
| Key | Required | Meaning |
|---|---|---|
version | yes | Must be 1 |
instance | yes | See below |
people | yes | At least one person |
defaults | no | Policy defaults for every resource |
openbao | yes | How Bouncer reaches OpenBao |
pairing | no | Which approval keys may pair |
push | no | Firebase push, or null for none |
resources | yes | At least one resource |
groups | no | Named groups of people, for personal credential sharing |
personal_credentials | no | Storage areas for people's own credentials |
instance
| Key | Meaning |
|---|---|
id | Lower-case letters, digits and hyphens. Goes into every signed statement. Never change it once devices are paired |
name | Display name |
url | https://host[:port], the address apps and requesters use. Carried in pairing codes |
people
A list of:
| Key | Meaning |
|---|---|
id | Lower-case ID, used in approvers, --person and --owner. Each person gets a human requester of the same name |
name | Display name |
defaults
Each of these can also be set on a single resource, which then overrides the default.
| Key | Default | Allowed | Meaning |
|---|---|---|---|
request_wait | 15m | 1m to 24h | How long a request waits for a decision |
credential_ttl | 5m | 30s to 1h | How long each OpenBao token lasts (never past the grant's end) |
durations.presets | [5m, 15m, 1h, 6h, 24h, 7d, always] | 1 to 12 entries, each 1m to 365d or always, no repeats | The quick choices on the approval screen |
durations.min | 1m | 1m to 365d | The shortest custom duration |
durations.max | 365d | 1m to 365d, at least min | The longest custom duration |
durations.always | true | Whether standing grants may be approved. The Bouncer project hasn't decided the policy for standing grants yet. Set this to false | |
durations.always_review | 90d | 1d to 365d | How often a standing grant must be re-confirmed |
self_approval | true | Whether people may approve their own requests and their own agents' | |
notification_approval | true | Whether approving from a notification is allowed (each device must also opt in) | |
require_hardware_uv | false | Whether only biometric hardware keys (platform-hw-uv) may approve | |
require_hardware_key | false | Introduced in 0.5.7; earlier servers refuse the key. In the current source (not yet released), requires verified Android-key or Windows TPM evidence for the current key plus per-use verification. A declared hardware-UV label alone fails. Independent of require_hardware_uv, whose UV-only claim rule is unchanged; both apply when both are set |
openbao
| Key | Meaning |
|---|---|
address | http(s)://host[:port], as both the server and requesters reach OpenBao |
ca_file | A PEM CA bundle for OpenBao's certificate, or null |
kit_prefix | The role kit's prefix (KIT_PREFIX, bouncer by default). Lower-case letters and digits in dash-separated parts, starting with a letter, up to 20 characters. Each resource uses the token role <kit_prefix>-issue-<resource id> |
approle.mount | The role kit's AppRole mount. Must start with the kit prefix and a dash (bouncer-approle) |
approle.role_id_file | The file holding the role_id (/run/secrets/bouncer-role-id in the compose kit) |
approle.secret_id_file | The file holding the secret_id |
ssh.approle.mount, .role_id_file, .secret_id_file | The SSH signer's own login, needed once any resource is an ssh_host. Its mount must start with the kit prefix and differ from the token login's |
Any change to this section needs a server restart.
pairing
| Key | Default | Meaning |
|---|---|---|
allow_software_keys | false | Allow approval keys kept in software. For test setups only |
allow_user_verified_keys | false | Allow phone keys that need biometrics for every signature (platform-hw-uv). Needed for iPhones |
allow_webauthn_keys | false | Allow Windows Hello keys |
require_verified_approval_keys | false | In the current source (not yet released): opt in to verified Android-key or Windows TPM evidence at key installation and every signing gate. Existing unverified keys also fail after reload. Keyless Windows bootstrap remains available. Incompatible with android_attestation: off |
android_attestation | prefer | required, prefer or off (Device keys) |
android_package | com.s6studios.bouncer | The Android app an attestation must name |
android_signing_cert_sha256 | the official upload certificate's | The SHA-256 of each certificate the app may be signed with (64 hex digits each) |
allow_software_keys, allow_user_verified_keys, allow_webauthn_keys and android_attestation: required are checked again whenever a device signs, so turning one off also stops keys that paired while it was on. android_package and android_signing_cert_sha256 apply only when a phone pairs. Turning on allow_software_keys or allow_user_verified_keys, weakening android_attestation, or changing android_package or the signing certificates counts as a loosening and is announced. Turning on allow_webauthn_keys is not announced. Turning off require_verified_approval_keys is a loosening and is announced; check-config and reload report its value. Dropping require_hardware_key also loosens proof requirements while require_hardware_uv remains set. With the new opt-in omitted, an existing UV-only rule still accepts declared claims; upgrading does not activate a policy. See key proof.
push
null turns push off. Otherwise:
| Key | Meaning |
|---|---|
fcm.project_id | The Firebase project ID |
fcm.service_account_file | The service-account key file, such as /run/secrets/fcm-service-account.json |
fcm_also | Needs server build 0.3.8+25 or later. Only while moving to another project: up to 4 more project_id and service_account_file pairs, tried in order after fcm. Each project and key file may appear once |
The key files are read at start-up and on every reload; a missing or broken one refuses the start or the reload.
resources
A list. Each resource:
| Key | Required | Default | Meaning |
|---|---|---|---|
id | yes | Lower-case letters, digits and single dashes, up to 40 characters. Unique. Not starting with pc- | |
name | yes | Display name | |
kind | yes | stored_secret, stored_api_key or ssh_host | |
description | no | none | Shown to requesters and approvers |
folder | no | Unfiled | Folder names joined by / |
credential_type | no | none | One of api_key, password, access_token, certificate, certificate_with_private_key, ssh_private_key, secret_key, key_pair, recovery_codes, otp_seed, other. A label for the apps' icons only. Servers before 0.5.0 refuse it |
kv | yes, except for ssh_host | A list of mount and path (without data/). An ssh_host has none | |
fields | no | none | Field names shown to requesters. Names only |
approvers | yes | Person IDs | |
requesters | no | any active requester | Requester names, or ["*"] for any |
request_wait, credential_ttl, durations, self_approval, notification_approval, require_hardware_uv, require_hardware_key (from 0.5.7) | no | from defaults | As in defaults |
allow_write | no | false | Accept store requests. Needs exactly one kv entry and write in the role kit's line |
lifecycle | no | false | Keep version history and allow expiry, scheduling and replacement from a paired app. Stored secrets and API keys only. Needs exactly one kv entry and lifecycle in the role kit's line. From 0.5.3; see setup, permissions and retention limits |
view | no | off | off, grant_holder or approver: who may view the value in the apps. Needs exactly one kv entry and view in the role kit's line. Not for ssh_host |
allow_device_view | no | false | Older form of view: approver. Give one or the other, not both |
downstream.system | with downstream | The other system's name | |
downstream.kind | with downstream | static_token | |
downstream.expires_at | no | none | When the credential expires at its system, as an RFC 3339 time |
ssh.principal | for ssh_host | The one account on the host: lower-case letters, digits, _, - and ., up to 32 characters, and not root | |
ssh.bind_source_address | no | true | Bind each certificate to the address the requester called from |
Adding a resource needs a restart. Removing one only needs a reload; its standing grants are suspended.
Check a candidate resource configuration
From 0.5.7, use bouncer-server --check-config with
--config before installing a new resource. It checks the candidate file
and OpenBao provisioning without applying it. Run it as the service user;
require exit 0 after the kit upgrade. See
Checking a file before you deploy it
for the login/session-token limits and all exit codes, and
Add a resource for the
kit, preflight, config and restart order. A new entry inherits defaults,
including its duration ceiling, unless it overrides them.
groups
A list of id and members (person IDs). Used only by personal credential sharing.
personal_credentials
A list of storage areas ("namespaces") where people create their own credentials from the apps. Each:
| Key | Default | Meaning |
|---|---|---|
id | The namespace's ID | |
label | from the ID, such as "Personal storage" | The name the apps show. Must differ from every other namespace's, ignoring case |
kv.mount, kv.prefix | Where the values go in OpenBao. The prefix leaves out data/, and mustn't overlap a resource's secret or another namespace. The role kit needs a matching personal line | |
creators | everyone | People or groups who may create here |
fields.names | any | The only field names allowed |
fields.max | 8 | Fields per credential, 1 to 32 |
per_owner | 50 | Credentials per person, 1 to 1000 |
lifecycle | false | Enable lifecycle for every credential in this namespace. The role kit's personal line for it needs lifecycle too (personal lifecycle). Turning it off later keeps recorded expiries, and saves that would prune an old version are still refused; see Credential expiry, replacement and history |
ceilings | required | The block must be present, even if empty (ceilings: {}) |
ceilings.credential_ttl, ceilings.durations | from defaults | The most a credential in this area may allow |
ceilings.reveal | false | Whether values may be viewed in the apps |
ceilings.always_approved | false | Whether an owner may set a credential to be approved automatically. Keep it false: this mode has two open problems (Approvals and access duration) |