РусскийRUEnglishEN

Pairing the desktop client with your account

Overview

For the Whisperer macOS client to work with your sessions, subscription, and knowledge base, you need to pair it with your account once. Installing the app by itself doesn't grant access — the device needs to be authorized (device auth).

Pairing is built on a secure one-time-code flow: the app initiates sign-in, you authenticate in the browser, receive a one-time code, and the browser returns you to the app. The code is one-time and lives for 30 minutes.

When to use

  • Right after installing the client and going through the permissions wizard.
  • When signing in on a new or reinstalled computer.
  • When the app stops seeing your account (you signed out of all devices, changed your password, etc.) and it needs to be paired again.

Step-by-step

  1. Initiate sign-in in the app. Open Whisperer on your Mac and start sign-in/pairing. The app requests a one-time code from the server (POST /v1/auth/desktop/code) and opens the pairing web page in your browser — /app/connect.
  2. Sign in to your account in the browser. On the /app/connect page, sign in with your e-mail and password. If you don't have an account yet — register and confirm your e-mail (see Registration and sign-in). Sign-in is impossible until your e-mail is confirmed.
  3. Confirm the device pairing. After sign-in, the web dashboard links the one-time code to your account.
  4. Return to the app. The browser automatically redirects you back to Whisperer via the whisperer://auth?code=...&state=... scheme. If a system prompt "Open in Whisperer?" appears — confirm it.
  5. Wait for the code-to-tokens exchange. The app exchanges the one-time code for access tokens and stores them in secure storage (encrypted). After that, the client is paired with your account.
  6. Verify. Make sure the app shows your account and plan. You can now start sessions.

Screenshots

📸 [Screenshot: sign-in initiation screen in the macOS client]

📸 [Screenshot: /app/connect web page with the sign-in form]

📸 [Screenshot: macOS system prompt "Open in Whisperer?" (the whisperer:// scheme)]

Common mistakes

  • Code expired. The one-time code lives for 30 minutes. If you took longer or got interrupted, pairing won't complete. Fix: return to the app and initiate sign-in again — a new code will be issued.
  • Browser didn't return to the app. If the whisperer:// scheme redirect didn't fire automatically, make sure Whisperer is installed in the "Applications" folder and repeat sign-in. When a system prompt to open the app appears — confirm it.
  • Sign-in fails — e-mail not confirmed. You can't sign in until your e-mail is confirmed with the 6-digit code. Confirm your e-mail and try again.
  • Multiple /app/connect tabs. Opening several pairing pages at once breaks the flow. Close the extras and run pairing again from the app.
  • Account frozen or banned. If the account status is frozen/banned, pairing won't complete — contact support.

Best practices

  • Run pairing right after installation, without delay — that way you'll comfortably fit within the code's 30-minute TTL.
  • Keep the /app/connect page open in only one tab.
  • If you changed your password or signed out of all devices, pair the client again — the old tokens are invalidated (token_version).
  • Don't pass the one-time code manually and don't share the whisperer://auth?... link — it's a secret for your device.

Related articles