デスクトップクライアントとアカウントのペアリング

概要

Whisperer の macOS クライアントをあなたのセッション、サブスクリプション、ナレッジベースと連携させるには、一度だけアカウントとペアリングする必要があります。アプリをインストールしただけではアクセス権は付与されません — デバイスの認可（デバイス認証）が必要です。

ペアリングは安全なワンタイムコード方式に基づいています。アプリがサインインを開始し、ブラウザで認証を行い、ワンタイムコードを受け取ると、ブラウザがアプリに戻します。コードはワンタイムであり、有効期間は 30 分 です。

利用する場面

クライアントをインストールし、権限ウィザードを完了した直後。
新しいコンピューターや再インストールしたコンピューターでサインインするとき。
アプリがアカウントを認識しなくなり（すべてのデバイスからサインアウトした、パスワードを変更したなど）、再度ペアリングが必要なとき。

ステップバイステップ

アプリでサインインを開始する。 Mac で Whisperer を開き、サインイン／ペアリングを開始します。アプリはサーバーにワンタイムコードを要求し（POST /v1/auth/desktop/code）、ブラウザでペアリング用 Web ページ — /app/connect を開きます。
ブラウザでアカウントにサインインする。 /app/connect ページで、メールアドレスとパスワードを使ってサインインします。まだアカウントをお持ちでない場合は、登録してメールアドレスを確認してください（登録とサインインを参照）。メールアドレスを確認するまでサインインはできません。
デバイスのペアリングを確認する。 サインイン後、Web ダッシュボードがワンタイムコードをあなたのアカウントに紐付けます。
アプリに戻る。 ブラウザは whisperer://auth?code=...&state=... スキームを使って、自動的に Whisperer へリダイレクトします。「Whisperer で開きますか？」というシステムプロンプトが表示された場合は、それを承認してください。
コードからトークンへの交換を待つ。 アプリはワンタイムコードをアクセストークンと交換し、安全なストレージ（暗号化済み）に保存します。その後、クライアントはあなたのアカウントとペアリングされます。
確認する。 アプリにあなたのアカウントとプランが表示されていることを確認してください。これでセッションを開始できます。

スクリーンショット

📸 [スクリーンショット：macOS クライアントのサインイン開始画面]

📸 [スクリーンショット：サインインフォームのある /app/connect Web ページ]

📸 [スクリーンショット：macOS のシステムプロンプト「Whisperer で開きますか？」（whisperer:// スキーム）]

よくある間違い

コードの有効期限切れ。 ワンタイムコードの有効期間は 30 分 です。それ以上時間がかかったり中断されたりすると、ペアリングは完了しません。対処法：アプリに戻って再度サインインを開始してください — 新しいコードが発行されます。
ブラウザがアプリに戻らない。 whisperer:// スキームのリダイレクトが自動的に実行されなかった場合は、Whisperer が「アプリケーション」フォルダにインストールされていることを確認し、サインインをやり直してください。アプリを開くためのシステムプロンプトが表示されたら、それを承認してください。
サインインに失敗する — メールアドレス未確認。 6 桁のコードでメールアドレスを確認するまでサインインできません。メールアドレスを確認してから再度お試しください。
複数の /app/connect タブ。 複数のペアリングページを同時に開くと、フローが壊れます。余分なタブを閉じて、アプリから再度ペアリングを実行してください。
アカウントの凍結またはBAN。 アカウントのステータスが frozen／banned の場合、ペアリングは完了しません — サポートにお問い合わせください。

ベストプラクティス

インストール後すぐに、遅れずにペアリングを実行してください — そうすれば、コードの 30 分間の TTL 内に余裕を持って収まります。
/app/connect ページは 1 つのタブだけで開いておいてください。
パスワードを変更した場合やすべてのデバイスからサインアウトした場合は、クライアントを再度ペアリングしてください — 古いトークンは無効化されます（token_version）。
ワンタイムコードを手動で渡したり、whisperer://auth?... リンクを共有したりしないでください — それはあなたのデバイス専用の秘密情報です。