Pairing browsers
Pair a browser with the gateway using a one-time code, and list, rename or revoke paired devices.
The gateway lets in only browsers you pair. You print a one-time code on the machine running the gateway, open the link on the device, and the browser gets a cookie that identifies it from then on.
Pair a browser
docker compose exec gateway airpost-gateway pair # mail only
docker compose exec gateway airpost-gateway pair --admin # also accounts and settings
It prints a code and a <public URL>/pair#<code> link. Open the link on the device, or open the web client and enter the code. Each code works once.
| Option | Default | |
|---|---|---|
--admin | off | Grants the admin scope (below) |
--name <device> | the browser’s name | The device’s name in devices list, up to 64 characters |
--ttl <time> | 10m | How long the code stays valid: 90s, 10m, 1h. At most 1h. |
--json | off | Print the result as JSON (airpost-gateway pair only) |
You can pair while the gateway is stopped; it reads the new code when it starts.
Scopes
A device paired without --admin gets mail reads, triage and drafts. A device paired with --admin can also use account, secret and engine methods, such as adding an IMAP account in Settings > Accounts. Pair only devices you control with --admin.
How long a device stays paired
The browser holds an HttpOnly, SameSite=Strict cookie, refreshed each time it opens a session. Over HTTPS it’s a __Host- cookie marked Secure. The gateway stores only hashes of the codes and tokens, in <profile>/gateway/devices.json.
A device unused for 180 days is dropped. An admin device is dropped after 30 days unused.
Several devices
Pair each device separately, with its own code. Give it a name you will recognize later:
airpost-gateway pair --name "Work laptop"
airpost-gateway pair --name "Phone"
airpost-gateway pair --admin --name "Home desktop" --ttl 5m
All devices see the same profile’s mail. A useful pattern is one --admin device you keep at home and mail-only devices everywhere else. To give a device admin later, revoke it and pair it again with --admin.
To share Airpost with someone else, don’t pair their browser with your gateway: they would read your mail. Give them their own profile (Users and devices).
List, rename and revoke
airpost-gateway devices list [--json]
airpost-gateway devices rename <id> <name>
airpost-gateway devices revoke <id>
On a server, prefix them with docker compose exec gateway. Revoking a device takes effect at once: the running gateway closes that device’s open sessions.
If you lose a device, revoke it. If you think a code leaked before it was used, let it expire, or revoke the device it paired.
To unpair every device, revoke each id from devices list. Codes that were printed but never used expire on their own.
Troubleshooting
| Symptom | Cause |
|---|---|
| The code is refused | It was already used or expired. The gateway logs pairing refused: unknown or expired code. |
Too many attempts. Wait a minute. | More than 5 tries a minute from one address. Behind a proxy, check AIRPOST_TRUSTED_PROXIES (Security). |
The browser shows This browser was unpaired. | The device was revoked or expired (180 days unused, 30 for admin). Pair it again. |
| Paired, but the session drops on every visit | The browser is blocking the cookie, or you’re switching between two hostnames. The cookie is tied to the public URL’s host. |