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 the app with your server
Pairing connects the app to your organisation's Bouncer server. A phone makes its own approval key while pairing; a Windows PC makes one later when you turn on Windows Hello. The key never leaves the device, and the server records the device and its key. After that, the server sends your requests to this device, and accepts approvals signed with its key.
What you need
-
A network connection that reaches your Bouncer server. If your organisation uses a VPN for Bouncer, connect it first; otherwise nothing extra is needed.
-
A pairing code from your administrator. They run
bouncer-admin device pairon the server, which shows:- a QR code to scan with a phone;
- a pairing string, one line starting
bouncer-pair:, to copy and paste; - the server address and a 12-character pairing code (shown as three groups of four), to type in by hand.
The code works once, and expires a few minutes after it was made. Ask for it when you're ready to pair. If your administrator sends you the pairing string, use a private channel: anyone who uses it first pairs as you.
On an Android phone
- Open Bouncer. You see To pair this phone with the command your administrator runs.
- Tap Scan QR code and point the camera at the QR code. Or tap Enter the code instead, then either Paste pairing string (if you copied the pairing string) or type the Server address and Pairing code, and tap Continue.
- On Name this phone, check the banner. It says Pairing with your server's address and As your name. If either is wrong, stop and ask your administrator.
- Check the Device name, or change it. It's shown in alerts and the approval log, so make it recognisable, for example "Alice's Pixel".
- Confirm every signature with biometrics is offered on Android phones that can make such a key. Tick it to require your fingerprint (or face, where strong enough) for every approval, instead of just an unlocked phone. Your server must allow these keys, and servers do not by default. If it refuses, tap Pair without biometrics. It is off unless you choose it.
- Tap Pair.
- You should see "Alice's Pixel is paired" and "It can now approve and deny requests on" your server. Your other paired devices get a New device paired alert.
- Tap Turn on notifications and allow them when Android asks, so you hear about requests without opening the app. Notifications show details only once the phone is unlocked.
You land in the Inbox. "Nothing waiting" is normal until someone asks for something.
Setting up biometric approvals later
If you paired without Confirm every signature with biometrics, Settings shows Set up biometric approvals. It needs a new pairing code, and your server must allow biometric keys. Your current pairing stays until the new setup succeeds.
On Windows
- Open Bouncer. You see Pair this PC.
- On the server, your administrator runs
bouncer-admin device pairand gives you the line under "Or copy this pairing string". Copy it. - In Bouncer, choose Paste pairing string. It fills in the Server address and Pairing code. (You can also type them.)
- Check the Device name, then choose Pair.
- Bouncer shows Pairing with your server's address and As your name. If both are right, choose Pair this PC. If either is wrong, stop and ask your administrator.
- Bouncer opens on the inbox. Your other paired devices get a New device paired alert.
Turn on approvals with Windows Hello
A PC pairs without an approval key, so at first it can only show requests and grants. To approve and deny on the PC:
- In the inbox (or in Settings), find the Windows Hello row and choose Enable. If the row is missing, your server does not accept Windows Hello keys (servers do not by default), or Bouncer cannot reach it. Ask your administrator.
- On Windows 11, Windows may ask "Let Bouncer Desktop create and use passkeys?" If it does, choose Yes.
- Windows asks you to confirm it's you. Choose Continue, then enter your Windows Hello PIN (or use your face or fingerprint). Windows asks twice: once to make the key and once to use it.
- You should see "Windows Hello approvals are on for this PC."
If you see "Windows Hello approvals need a PC with a security chip (TPM)", this PC can't approve; approve on another paired device instead. If you see "This server doesn't accept Windows Hello keys", your administrator hasn't turned them on.
Once approvals are on, the app marks this key as not checked by hardware. In 0.5.6 and earlier, Bouncer does not check whether a Windows Hello key is held in the TPM. 0.5.7 checks a TPM attestation when Windows supplies one, but no real PC has passed that check yet (Device keys).
If you chose No to the passkeys question, turn Bouncer Desktop on under Settings > Privacy & security > Passkeys > Let apps create and use passkeys, then choose Enable again. Windows Hello also needs a PIN, which you set up under Settings > Accounts > Sign-in options.
More than one device
You can pair a phone and a PC. Each request goes to all your devices, and answering on one closes it on the others. Each device's Settings lists the others under Your other devices, with whether each one approves.
The server check on Windows
On Windows, after you type the server address (press Enter, or move to the
next field), Bouncer checks it before any code is sent. It asks the server's
/v1/health, which needs no sign-in and changes nothing, and shows four
separate lines:
- Reachable: the PC got a connection to the server.
- Secure connection: the server's certificate is valid for the name you typed, in date, and from a certificate authority this PC trusts.
- Bouncer API: it answered as a Bouncer server this app can talk to.
- Pairing: always "Not paired yet" here. Pairing happens when you choose Pair, with the code.
The check gives up after 10 seconds. Retry runs it again. Changing the address stops a check that's still running and clears its result, and Pair checks the address first if it hasn't passed yet. Pairing can't start until the check passes.
Details opens the server check details: the address and the URL checked, each step's result, the server's name and version, and the certificate's subject, names, issuer, validity dates, SHA-256 fingerprint and validation result. If the secure connection failed before the server sent a certificate, it says so instead. It never shows the pairing code.
Bouncer never accepts a certificate the PC doesn't trust, and never falls back to plain HTTP or follows a redirect. If your organisation uses its own certificate authority, it has to be installed in Windows' certificate store first (ask your administrator).
| What the check says | What to do |
|---|---|
| "Couldn't find …" | Check the address for typos, and check the PC's network connection. |
| "…its vault isn't ready", "…can't reach its database" (from 0.5.7) or "…the Bouncer server behind it isn't answering" | The server is running but cannot serve. Tell your administrator; there is nothing to fix on the PC. |
| "… refused the connection" | Check the address, including any port number. |
| "This PC can't get to …" or "… didn't answer in time" | Check the address and your network connection, then Retry. |
| "… answered, but not over HTTPS" | Use the server's https:// address. |
| "The server's certificate isn't from a certificate authority this PC trusts" | Ask your administrator. If they use their own certificate authority, it must be installed on the PC. |
| "The server's certificate expired …" or "isn't valid yet" | Ask your administrator to renew it, or check the PC's date and time. |
| "The server's certificate is for a different name" | Check the address. Use the name the certificate is for, which Details shows. |
| "This address sends Bouncer on to …" | Enter the Bouncer server's own address. |
| "… isn't a Bouncer server" or "This Bouncer server uses API …" | Check the address with your administrator. The app or the server may need updating. |
If pairing fails
| What the app says | What to do |
|---|---|
| "This code has expired or was already used." | Ask for a new code. Each works once, for a few minutes. |
| "That doesn't look like a pairing code. It has 12 letters and numbers." | Check you typed or pasted the whole code. |
| "Can't reach this address." | Check the address and your network connection. |
| "This address answers, but it isn't a Bouncer server this app can pair with." | Check the address with your administrator. The server may also need upgrading. |
| "Too many wrong codes." | Wait up to 10 minutes, then try again. Your code still works if it hasn't expired (codes last 5 minutes unless your administrator chose another time); otherwise ask for a new one. |
| "Bouncer can't use the camera." | Allow camera access for Bouncer in Android settings, or tap Enter the code instead. |
| "That isn't a Bouncer pairing code." | You scanned a different QR code. Scan the one bouncer-admin device pair shows. |
| "Your server only pairs phones that keep their approval key in secure hardware, and this phone's key isn't." | This phone can't pair with this server. Use another phone. |
| "This phone can't keep a fingerprint- or face-protected key in secure hardware, so biometrics can't confirm each signature here." | Tap Pair without biometrics. |
| "This phone couldn't make a key that needs your fingerprint or face." | Set up a fingerprint in Android settings, or tap Pair without biometrics. |
| "Your server doesn't accept keys that need your fingerprint or face for every signature." | Tap Pair without biometrics, or ask your administrator. |
| "This phone couldn't make its approval key. Unlock it, then try again." | Unlock the phone and try again. A screen lock must be set. |
| "Your server paired this phone, but the phone couldn't save the pairing." | Ask your administrator to run the bouncer-admin device revoke command the message shows, then pair again with a new code. |
After a refusal, the app says either "Nothing was paired." or "Your existing pairing was kept."