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

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

Pair a device

Pairing links a phone or PC to a person. Afterwards the device shows that person's requests and, if it has an approval key, can approve and deny them. This page covers the admin side. The person's side is in the app pages.

Before you start:

  • The person must be in people in the config file.
  • Their device must be able to reach the server's HTTPS address (instance.url).
  • For an iPhone, the config must have pairing.allow_user_verified_keys: true. Every iPhone approval key needs Face ID or Touch ID for each signature, and the server refuses that kind of key unless this is on.
  • For a Windows PC that will approve, the config must have pairing.allow_webauthn_keys: true. Windows Hello keys are refused without it. The PC still pairs, but it can't approve.

Both are off by default. After changing them, run docker compose exec bouncer bouncer-admin config reload. Which keys may pair has the full list.

Make a pairing code

On the server, in a terminal big enough to show a QR code:

cd ~/bouncer/deploy/compose
docker compose exec bouncer bouncer-admin device pair --person alice

Expected result: two lines, a QR code between blank lines, then the same information in two other forms:

Scan this with the Bouncer app.
It works once, for 5 minutes, and pairs as Alice.

(the QR code, drawn with block characters, about 20 lines)

Or copy this pairing string and choose Paste pairing string in the app:
bouncer-pair:v1?code=K7QM2XRD9FTA&server=https%3A%2F%2Fbouncer.example.com

Or type these into the app:
  Server address  https://bouncer.example.com
  Pairing code    K7QM-2XRD-9FTA

The code expires at 2026-11-15T10:05:00Z.

The code works once, and expires after 5 minutes. --ttl changes that, from 1m to 30m:

docker compose exec bouncer bouncer-admin device pair --person alice --ttl 15m

How each app takes the code:

AppHow
Android, iOSScan the QR code, or type the address and code
WindowsPaste the pairing string, or type the address and code. The Windows app has no QR scanner

The QR code and pairing string carry the code itself. Treat them like a password for the next few minutes: show them only to the person who is pairing, and don't paste them into chat.

Check the result

docker compose exec bouncer bouncer-admin device list

The new device appears as active, with the name the person gave it. APPROVES is yes for a phone. For a Windows PC it says no until the person turns on Windows Hello approvals in the app's settings (which needs pairing.allow_webauthn_keys: true in the config).

When the new device pairs, the person's other active devices get a "New device paired" alert, and the approval log records device_paired with the address it paired from. If someone gets that alert and didn't pair anything, revoke the new device at once.

Which keys may pair

The pairing section of the config decides which approval keys the server accepts. The defaults are the strict ones:

SettingDefaultMeaning
allow_software_keysfalseA key kept in software rather than the device's secure hardware. Leave it off; only test setups turn it on
allow_user_verified_keysfalsePhone keys that need a biometric check on every signature (platform-hw-uv). iPhones only pair with this on, because every iOS key is this kind
allow_webauthn_keysfalseWindows Hello keys on Windows PCs
android_attestationpreferWhether an Android phone's claim to hold a hardware key must be proven with Google's key attestation: required, prefer or off

Device keys and user verification explains what each one means for security.

When pairing fails

What the person sees, or the log saysWhat to do
The code is refused as invalid or expiredCodes work once and for a few minutes. Make a new one
rate_limitedMore than 10 wrong codes from one address in 10 minutes. Wait, then try again with a fresh code
The app can't reach the serverThe device must reach instance.url over HTTPS. Check the address and the device's network or VPN, and that instance.url matches what your reverse proxy serves
An iPhone is refused with "Your server doesn't accept keys that need Face ID or Touch ID, and every approval key on iPhone does"Set pairing.allow_user_verified_keys: true and reload
An Android phone is refused under android_attestation: requiredThe phone couldn't prove a hardware key. Check the app is the official build; see Device keys

How this was checked

In our test run, a pairing code was made with bouncer-admin device pair, and a command-line stand-in for the phone (a test-only program in the repository) paired with it and then approved and denied requests. The QR code itself, and pairing real Android, iOS and Windows apps, weren't part of that run.

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