Home Assistant の長期アクセストークン：作り方、管理者が必要な理由、「接続できるのに何も表示されない」

結論から

長期アクセストークンは、アプリやスクリプトのためのパスワードの代わりです。Home Assistant のプロファイルの セキュリティ タブにある 長期間有効なアクセストークン で作成し、Home Assistant が表示するのは一度だけです。有効期間は10年です。一部のアプリでは管理者のトークンが必要です。/api/template のように、管理者以外のユーザーをすべて 401 で拒否する API があるためです。

この記事の残りでは、トークンとは何か、どこにあるか、壊さずにコピーする方法、管理者かどうかが重要な理由、2つの curl コマンドでトークンをテストする方法、トークンを管理する方法を、ひとつずつ説明します。実例として取り上げるのは、Amazfit ウォッチ向けの Home Assistant アプリ AmazHA です。トークンが必要で、それも管理者のトークンが必要で、コピー＆ペーストで崩れたトークンにも対処しなければならないという、すべての論点に当てはまるからです。

長期アクセストークンとは

長期アクセストークンは、プログラムがログイン画面を通らずに、あなたの Home Assistant ユーザーとして動作するための認証情報です。Web インターフェイスにログインすると、Home Assistant はブラウザに短期のアクセストークン（30分）と、それを更新するためのリフレッシュトークンを渡します。スクリプトやスマートフォンアプリ、ウォッチアプリでは、このログインの流れを簡単には実行できません。そこで Home Assistant は、もう1種類のトークンを用意しています。手動で作成し、一度コピーしてプログラムに渡すトークンです。

実際に重要な性質は3つです。

• 有効期間は10年です。 Home Assistant 自身の認証 API のドキュメントには、長期トークンは「10年間有効」と書かれており、プロファイルページにも、各トークンは作成から10年間有効であると表示されます。
• 表示されるのは一度だけです。 Home Assistant はトークンそのものを保存しないため、もう一度表示することはできません。なくした場合は、新しく作成します。
• トークンは作成したユーザーそのものです。 トークンには、作成したユーザーの権限がそのまま付き、それ以上でも以下でもありません。管理者が作成したトークンは、署名するすべてのリクエストで管理者として扱われ、一般ユーザーが作成したトークンは一般ユーザーとして扱われます。

トークンは、すべてのリクエストで HTTP ヘッダーに入れて送られます。

Authorization: Bearer <your token>

クライアントがすることはこれだけです。ユーザー名もパスワードもセッションもなく、このヘッダーに有効なトークンが入っているリクエストは、そのユーザーからのものとして受け付けられます。

どこにあるか

長期アクセストークンは、自分のユーザープロファイルの セキュリティ タブで作成します。Home Assistant アプリでもブラウザでも、手順は同じです。

1. サイドバー（スマートフォンでは ≡ メニュー）を開き、いちばん下にある自分の名前をタップします。
2. プロファイルで セキュリティ タブを開きます。
3. そのタブを下にスクロールすると 長期間有効なアクセストークン のセクションがあり、すでにあるトークンの一覧と トークンの作成 ボタンが表示されます。

Home Assistant のユーザー向けドキュメントにも同じことが書かれています。ユーザープロファイル › セキュリティは、パスワードの変更、多要素認証の設定、リフレッシュトークンの管理も行うページです。

「見つからない」とき

いちばん多い理由はタブです。プロファイルは一般的な設定（言語、テーマなど）のタブで開き、トークンのセクションは セキュリティ タブにあります。古いガイドの多くには「プロファイルページのいちばん下までスクロール」とありますが、それはプロファイルがタブに分かれる前の話です。

ほかに考えられる理由は2つです。

• ほかの人のトークンを探している。 各ユーザーが表示・管理できるのは、自分のトークンだけです。家族のほかの人が作成したトークンは自分のプロファイルには表示されず、そこから削除することもできません。
• 思っているのとは別のユーザーでログインしている。 サイドバーのいちばん下の名前を確認してください。アプリに管理者のトークンが必要な場合（後述）は、作成する前に、その名前が管理者のものであることを確かめてください。

作成してコピーする

トークンの作成は4回のタップで済みますが、問題が起きやすいのは正しくコピーするところです。手順は次のとおりです。

1. セキュリティ タブの 長期間有効なアクセストークン の下で、トークンの作成 をタップします。
2. Home Assistant がトークンの名前を尋ねます。アプリの名前（例：AmazHA）にしておきましょう。名前は自分のトークンの中で重複できません。
3. 次のダイアログにトークンが表示され、「アクセストークンをコピーしてください。再度表示されることはありません」という趣旨の警告が出ます。今すぐ、全体をコピーしてください。
4. ダイアログを閉じます。トークンが名前と作成日とともに一覧に表示されます。

トークンは英字、数字、-、_ からなる長い文字列で、ドットで区切られた3つの部分でできています。コピーの問題のほとんどは、この長さが原因です。1行に収まらないので、雑に選択すると一部だけになりがちです。また、長い文字列を画面上で省略記号（…）で短く表示し、表示されたとおりにコピーするアプリもあります。

トラブルを避けるための習慣を紹介します。

• 手動で選択せず、ダイアログのコピーボタンを使う。
• 必要なアプリに直接貼り付ける。 チャット、メール、メモアプリを経由すると、見えない文字、タイポグラフィ用の引用符、改行が入ることがあります。
• 前に Bearer を付けない。 アプリがヘッダー全体を明示的に求めている場合を除きます。ほとんどのアプリは、この語を自分で付け加えます。
• 別のデバイスで必要なら、最初のトークンを送り回すのではなく、そのデバイス用に2つ目のトークンを作成する。

一部のアプリで管理者のトークンが必要な理由

一部のアプリで管理者のトークンが必要なのは、Home Assistant がいくつかの API エンドポイントを管理者専用にしていて、トークンにはそのユーザーができることしかできないからです。いちばんわかりやすい例がテンプレートのエンドポイント POST /api/template で、サーバー上で Jinja テンプレートを処理して結果を返します。

Home Assistant のソースコードでは、これを提供するビュー、homeassistant/components/api/__init__.py の APITemplateView の post メソッドに、@require_admin デコレーターが付いています。このデコレーターはトークンの背後にいるユーザーを確認し、管理者でなければ Unauthorized を発生させます。Home Assistant の HTTP 層はこれを 401 Unauthorized に変換します。REST API のドキュメントでも、このエンドポイントには「Admin」と記されています。

管理者専用なのはこれだけではありません。REST API はおおよそ次のように分かれています。

では、アプリがそもそもテンプレートのエンドポイントを必要とするのはなぜでしょうか。通常の REST エンドポイントでは得られない情報があるからです。いちばんわかりやすいのが エリア です。/api/states はすべてのエンティティを状態と属性とともに返しますが、それが属するエリアは返さず、REST API にはエリアを一覧にするエンドポイントもありません。テンプレートならそれを問い合わせられます。area_id(entity_id) と area_name(...) は、エンティティ自身の設定またはそのデバイスの設定から、Home Assistant が各エンティティについて判断したエリアを返します。Home Assistant のダッシュボードのように家を部屋ごとに表示したいアプリは、そのためにテンプレートを処理させる必要があり、それには管理者が必要なのです。

アプリに管理者権限を与えてもよいのか

Home Assistant 自身のセキュリティに関するアドバイスは、管理者のアクセス権を必要なアカウントにだけ与える、というものです。/api/template を必要とするアプリはまさにそのケースで、妥当な対応方法は2つあります。

• 自分の管理者ユーザーでトークンを作成する。 いちばん簡単な方法です。トークンは名前付きで自分のプロファイルに表示され、削除すればそのアプリの分だけを取り消せます。
• アプリ専用の管理者ユーザーを作成する。 設定 › People（人物）でユーザーを作成し、そのユーザーで一度ログインして、そこでトークンを作成します。「最終使用」の情報が自分のものと分かれ、あとでユーザーごと無効にすることもできます。アプリが使っている間はユーザーを有効のままにしてください。無効化されたユーザーのトークンは動かなくなります。アプリが自宅の外からも接続する場合は、Local access only（ローカルアクセスのみ）にチェックを入れないでください。理由は後述の 401 のセクションで説明します。

いずれの場合も、トークンはパスワードと同じように大切に扱ってください。管理者のトークンには、あなたが Home Assistant でできることがすべてできます。

「接続できるのに何も表示されない」：/api/template の 401

アプリの接続には成功しているのに何も表示されない場合、原因はほぼ必ず、管理者ではないユーザーのトークンです。多くのアプリは GET /api/ でテストし、このエンドポイントは有効なトークンならどれでも受け付けるので、接続テストは通ります。状態も読み取れます。失敗するのはテンプレートのリクエストだけで 401 になり、そのテンプレートからデバイスの一覧を作るアプリは、表示するものが何もなくなります。

アプリから見た流れは次のとおりです。

1. トークン付きの GET /api/：200、{"message": "API running."}。アプリは「接続済み」と表示します。
2. GET /api/states/...：200。状態は取得できます。
3. エンティティをエリアに対応付けるための POST /api/template：401。エリアがないので部屋もなく、画面は空になります。

わかりにくいのは、ほかには何もおかしなところがないことです。アドレスは正しく、トークンは有効で、Home Assistant も動いています。操作さえ動くことがあります。POST /api/services/... は一般ユーザーにも開放されているので、同じトークンでアプリから照明を切り替えることもできるのです。

Home Assistant に表示されるもの

Home Assistant は、送った 401 を、管理者チェックによるものも含めてすべてログインの失敗として数えます。ログには、リクエスト元のアドレス（自宅なら通常はスマートフォンかサーバー）を示す「Login attempt or request with invalid authentication from …」で始まる警告が記録され、Web インターフェイスには Login attempt failed（ログインの試行に失敗）の通知が表示されます。ログイン試行回数による IP の禁止を有効にしていると、この 401 が一定数に達した時点でそのアドレスが禁止されます。それ以降、そのアドレスはすべてのリクエストで 403 Forbidden になり、ip_bans.yaml から削除して Home Assistant を再起動するまで解除されません。

ですから、自分のスマートフォンを指す「Login attempt failed」の通知が繰り返し出る場合、削除済みのトークンのほかに、一般ユーザーのトークンを持つアプリが管理者専用のエンドポイントを呼び出していることも、原因のひとつとして考えられます。

AmazHA はこれをどう検出し、どう伝えるか

/api/template でエリアを読み取る AmazHA は、ウォッチを空のままにせず、このケースを意図的にチェックしています。

• 「接続」をタップしたとき、スマートフォンはまず GET /api/ でアドレスを確認し、続いてごく簡単なテンプレート {{ 1 }} を /api/template に送ります。このテンプレートが 401、403、400 で拒否されると、トークンは管理者のものではないと判定されます。すると Home Assistant の画面には 接続済み ✓ と表示され、その下にオレンジの行で「接続済みですが、このトークンには管理者権限がないため、時計がエンティティを読み込めません。Administrator ロールの Home Assistant ユーザーで長期アクセストークンを作成し、上に貼り付けてください。」と表示されます。
• ウォッチでは、エリアのテンプレートが拒否されて部屋を読み込めない場合、ホームに一般的なオフラインではなく、管理者トークンが必要 · 「トークンに管理者権限がありません — Home Assistant の管理者ユーザーを使ってください」というバナーが表示されます。
• AmazHA の設定から送れるサポートレポート には、トークンが管理者のものと認識されたかどうかを示す「HA token」の行があり、トークン自体は一切含まれません。

対処法はどの場合も同じです。管理者としてログインした状態で新しい長期アクセストークンを作成し、貼り付けて、もう一度 接続 をタップします。困ったときはのステップ5の動画で紹介しています。

ユーザーが管理者かどうかを確認する方法

設定 › People（人物）を開き、Users（ユーザー）タブを開きます。管理者の場合、Group（グループ）の列に Administrators（管理者）と表示されます。ユーザーを開くと Administrator（管理者）のスイッチがあり、「管理者は、ユーザー、デバイス、オートメーション、ダッシュボードを管理できます」という趣旨の説明が添えられています。

もっと手早い確認方法もあります。ログインしているアカウントのサイドバーに 設定 の項目がまったくなければ、そのユーザーは管理者ではありません。Home Assistant は設定パネルを管理者専用として登録しているため、一般ユーザーには表示されないのです。その場合は、ログアウトして管理者でログインし、そこでトークンを作成してください。

curl で自分で確認する

同じネットワーク上のパソコンから、2つの curl コマンドで、どのトークンも1分でテストできます。1つは有効なトークンならどれでも通る /api/ に対して、もう1つは管理者のトークンだけが通る /api/template に対してです。例では Home Assistant のアドレスとして 192.168.1.50:8123 を使っているので、ご自身のアドレスに置き換えてください。macOS や Linux のターミナルでは、書かれたとおりに実行できます。

トークンをシェルの履歴に残さないように、まず変数に読み込みます。コマンドが入力を待ったらトークンを貼り付け、Enter キーを押します。

read -rs HA_TOKEN

テスト1：トークンは有効か？

curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $HA_TOKEN" \
  http://192.168.1.50:8123/api/

有効なトークンなら、{"message":"API running."} と HTTP 200 が返ります。末尾のスラッシュに注意してください。エンドポイントは /api/ で、/api ではありません。

テスト2：トークンは管理者のものか？

curl -s -w "\nHTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{{ 1 }}"}' \
  http://192.168.1.50:8123/api/template

管理者のトークンなら、処理されたテンプレート 1 と HTTP 200 が返ります。一般ユーザーのトークンなら HTTP 401 が返ります。

2つの結果をあわせて読む方法は次のとおりです。

注意点が2つあります。まず、これはパソコンからトークンをテストするものです。スマートフォンのアプリは、特に外出先では、別の経路で Home Assistant にアクセスすることがあります。次に、テスト1が通るだけでは、エリアを必要とするアプリについてはほとんど何も証明できません。一般ユーザーのトークンでも通るのが、まさにこのテストだからです。

「Local access only」による 401

Local access only（ローカルアクセスのみ）が有効なユーザーは、ローカルネットワークからしかログインできず、Home Assistant はそのユーザーのトークンにも同じルールを適用します。ネットワークの外のアドレスからのリクエストや、Home Assistant Cloud 経由で届いたリクエストは、自宅では問題なく動く同じトークンでも 401 で拒否されます。アプリが自宅の Wi-Fi では動くのに、外出先では 401 で失敗する場合は、リモートアドレスを疑う前に 設定 › People（人物）でそのユーザーを開き、このスイッチを確認してください。リモートアドレスそのものについては、外出先でもウォッチから Home Assistant を使うをご覧ください。

貼り付けの問題

正しく見えるトークンでも、間違っていることがあります。貼り付けたものが、Home Assistant から渡されたものと同じとは限らないからです。Home Assistant はトークンを1文字ずつ比較するので、1文字でも多かったり足りなかったりすれば無効なトークンになり、401 になります。よくある原因は次のとおりです。

どれも治し方は同じです。ダイアログのコピーボタンでトークンをもう一度コピーし、直接貼り付けます。ダイアログをすでに閉じている場合、そのトークンは取り戻せません。新しいトークンを作成し、古い項目を削除してください。

AmazHA が取り除くもの、受け付けないもの

AmazHA は、直せるケースには自分で対処します。トークンを保存するときと、スマートフォンがリクエストのためにトークンを読み込むときの両方です。

• 取り除くもの： スペース、改行、ゼロ幅文字、ノーブレークスペース、バイトオーダーマーク、ソフトハイフン、方向制御文字。トークンのどこにあっても取り除きます。英字、数字、-、_、ドットでできている Home Assistant のトークンには、これらはどれも含まれないからです。
• 両端から除去するもの： 通常の引用符とタイポグラフィ用の引用符、バッククォート、ギユメ。
• 先頭から外すもの： 貼り付けられた Bearer （大文字・小文字を問わず）。AmazHA がこの語を自分で付け加えるためです。

取り除いても直せないのは、トークンには含まれない目に見える文字で、典型的なのは途中で切れたコピーの … です。AmazHA は推測せず、そのトークンを一切送信しません。そのため、Home Assistant にリクエストは届かず、ログインの失敗として数えられることもありません。設定の Home Assistant の画面には トークンが無効です と表示され、「トークンに Home Assistant のトークンにはあり得ない文字が含まれています — 多くの場合、途中で切れたコピーです（…）。Home Assistant のプロフィール › セキュリティ からトークン全体をもう一度コピーし、上に貼り付けてください。」と説明されます。ウォッチには トークンを確認 · 「無効な文字が含まれています — 貼り付け直してください」と表示されます。これが困ったときはのステップ6です。

安全に保つ

長期トークンはどれも、10年間失効しないパスワードとして扱ってください。アプリごとに1つのトークンを作り、どのアプリのものかがわかる名前を付け、そのアプリを使わなくなった日に削除します。具体的には次のとおりです。

• アプリやデバイスごとに1つのトークン。 同じトークンを3つのプログラムに渡すと、ほかの2つを壊さずに1つだけを取り消すことができず、どれが呼び出しているのかもわかりません。
• アプリの名前を付ける。 「AmazHA」「バックアップスクリプト」「壁掛けタブレット」など。あとで一覧に表示されるのは名前だけで、トークン自体は二度と表示されません。
• ときどき一覧を見る。 各項目には作成日時と、使われたことがあれば最終使用の日時と場所が表示されます。何か月も使われていないトークンは、削除の候補です。
• 削除して取り消す。 セキュリティ タブで、トークンを名前で探して削除します。そのトークンを使っていたアプリは次のリクエストで 401 になって失敗し、ほかには何も影響しません。
• トークンが漏れたかもしれないときは、削除して新しいトークンを作成します。1つのトークンを取り消す方法は削除だけで、新しいトークンは1分でアプリに設定できます。
• トークンをサポートへの問い合わせ、フォーラムの投稿、スクリーンショットに貼り付けない。 まともなアプリの診断情報には、トークンは必要ありません。

同じタブですべてのリフレッシュトークンを削除すると、各デバイスからログアウトしますが、Home Assistant の確認ダイアログにもあるとおり、現在のセッションと長期トークンは残ります。長期トークンは1つずつ取り消します。

AmazHA の場合

AmazHA に必要なのは、管理者の長期トークン1つだけで、Zepp アプリ内の AmazHA の設定で一度入力します。その1つのトークンでローカルとリモートの両方のアドレスに対応し、トークンはスマートフォンに保存されたままです。接続の欄は、フル版のロックを解除すると使えるようになります（一度だけの購入で、サブスクリプションはありません。フル版のロックを解除をご覧ください）。そのあとの手順は次のとおりです。

1. 上で説明したとおり、管理者としてトークンを作成します（Home Assistant に接続のステップ1〜3）。
2. Zepp アプリで プロフィール › お使いのウォッチ › アプリ › AmazHA › 設定 に進み、Home Assistant をタップします（ステップ4）。
3. ローカルURL (LAN) に自宅でのアドレス（例：http://192.168.1.50:8123）を入力し、外出先でもウォッチを使いたい場合は リモートURL に外部からのアドレスを入力します。どちらの欄も空欄のままでかまいません。
4. トークンを 長期アクセストークン に貼り付けます（ステップ7）。
5. 接続 をタップします。アドレスを両方設定した場合は、LAN とリモートのそれぞれの結果が表示されます。アドレスが1つの場合は 接続済み ✓ と表示されます。トークンが管理者のものでない場合は、その下に先ほど説明したオレンジの行が表示されます。

1つのトークンで2つのアドレス

リモートアドレス用に2つ目のトークンは必要ありません。トークンはアドレスではなくユーザーに属するもので、リクエストが自宅の Wi-Fi 経由でも外部からでも、同じトークンが有効です。自宅では AmazHA はローカルアドレスを使い、リモートアドレスはスマートフォンが外にあるときにだけ使います。唯一の例外は先ほどの Local access only のユーザーで、そのトークンは設計上、外部からは拒否されます。

トークンの行き先と、行かない先

ウォッチが Home Assistant と直接通信することはありません。通信するのはスマートフォンで、Zepp アプリを通じて行い、トークンもそこ、つまりスマートフォンに保存されます。トークンは、スマートフォン自身のリクエストの Authorization ヘッダーに入れて、Home Assistant サーバーにだけ送信されます。ウォッチに送られることはなく、ウォッチはスマートフォンとの Bluetooth 接続で、表示する内容だけを受け取ります。AmazHA にはトークンが経由するような独自のサーバーはなく、サポートレポートにもトークンは含まれません。

スマートフォンがトークンを使って行うリクエストは、次のとおりです。

最後の行はウォッチセンサーの機能で、Amazfit の心拍数、歩数、バッテリーなどを Mobile App 連携のデバイスとして Home Assistant に送信します。Amazfit のデータを Home Assistant に送るで紹介しています。

AmazHA がトークンについて何か表示したとき

オフライン の下にある小さなコードは、サポートのためのものです。お問い合わせの際は、ウォッチの写真があれば、何が失敗したのかが正確にわかります。ウォッチに表示されるそのほかのメッセージについては、困ったときはをご覧ください。