Docs

Pair your phone

A QR code, a key in the phone, no token to type.

Pairing introduces your phone to your server once. The phone makes a key that never leaves its secure hardware, the server keeps only the public half, and from then on the phone proves who it is on every connection. There is no password to type and no token that could be copied.

Turn pairing on in the config, restart core, then make a one-time code. The code works once and expires after five minutes.

  1. Turn pairing on

    Add this to your config. The deploy example already has it.

    avni.toml
    [auth]
state_dir = "/var/lib/avni/auth"      # dev: "dev/auth"

  2. Make a pairing QR code

    bash
    # systemd
sudo -u avni avni-core pair --state-dir /var/lib/avni/auth --url ws://100.x.y.z:7444/v1/session
# docker
docker compose exec avni-core avni-core pair --state-dir /var/lib/avni/auth --url ws://100.x.y.z:7444/v1/session
# from source
scripts/dev-core.sh --pair

    It prints a QR code and the same link as text.

  3. Scan it with the phone's camera

    Open the link the camera shows. Avni asks Pair with this server? and shows the address. Check it, then tap Pair. If the camera does not offer the link, copy the printed link to the phone and tap it.

  4. Talk

    Settings, Connection now says paired. Tap the orb.

Managing devices

bash
avni-core devices --state-dir /var/lib/avni/auth             # who is paired
avni-core revoke <start-of-id> --state-dir /var/lib/avni/auth  # refuse that phone from its next connection

Lost or replaced a phone? Revoke it, then pair the new one with a fresh code. On the phone, Unpair this phone (two taps) deletes its key.

What is happening

  • The code is ten characters, stored only as a hash, valid five minutes, and used once. Eight wrong tries in a minute lock pairing out for the rest of that minute.
  • The phone's key is Ed25519 on Android 13 and newer, ECDSA P-256 on older versions, held in the Android Keystore.
  • Each connection starts with a signature over the device id and the time. The server accepts it within five minutes of its own clock and never twice, so a captured copy is useless.