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
peoplein 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:
| App | How |
|---|---|
| Android, iOS | Scan the QR code, or type the address and code |
| Windows | Paste 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:
| Setting | Default | Meaning |
|---|---|---|
allow_software_keys | false | A key kept in software rather than the device's secure hardware. Leave it off; only test setups turn it on |
allow_user_verified_keys | false | Phone 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_keys | false | Windows Hello keys on Windows PCs |
android_attestation | prefer | Whether 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 says | What to do |
|---|---|
| The code is refused as invalid or expired | Codes work once and for a few minutes. Make a new one |
rate_limited | More than 10 wrong codes from one address in 10 minutes. Wait, then try again with a fresh code |
| The app can't reach the server | The 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: required | The 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.