hass-config-flow

Home Assistant REST API

ドキュメント：https://developers.home-assistant.io/docs/api/rest/

NixOS の extraComponents にはインテグレーションのコードが含まれていますが、設定フローのみのインテグレーション（Spotify、Matter、HomeKit Controller、Cast など）は、セットアップの完了に REST API または UI が必要です。

hass-cli（調査や簡単な呼び出しに推奨）

NUC には home-assistant-cli がインストールされています。エンティティの一覧表示、サービスの呼び出し、デバイスやエリアの管理、イベントの監視には、生の curl よりこちらを優先してください。

# On NUC (after getting a token):
export HASS_SERVER=http://localhost:8123
export HASS_TOKEN=<token>

hass-cli state list 'light.*'          # list entities by glob
hass-cli state get light.office        # get single entity (yaml)
hass-cli service call homeassistant.toggle --arguments entity_id=light.office
hass-cli device list                   # all devices with area
hass-cli area list                     # all areas
hass-cli device assign Kitchen --match "Kitchen Light"  # bulk assign area
hass-cli event watch                   # watch all events
hass-cli event watch deconz_event      # watch specific event type
hass-cli -o yaml state list            # yaml output
hass-cli -o json state list 'light.*' | jq '[.[] | {entity: .entity_id, name: .attributes.friendly_name, state: .state}]'
hass-cli -o json state list 'light.*' | python3 -c "import json,sys; d=json.load(sys.stdin); print([x['entity_id'] for x in d if x['state']=='on'])"

注： 現在の HA では hass-cli info は動作しません（非推奨のエンドポイントを使用しています）。ほかのコマンドはすべて動作します。

設定フロー、アプリの認証情報、および hass-cli では対応していない操作には、以下の生の curl を使用してください。

API のクエリ（SSH のインライン実行）

scripts/ 内のスクリプトはローカルにあるため、NUC 上でパスを指定して参照することはできません。代わりに、SSH コマンドをインラインで実行してください。

トークンを取得する

TOKEN=$(ssh nuc "sudo python3 -c '
import hashlib, hmac, base64, time, json
auth = json.load(open(\"/var/lib/hass/.storage/auth\"))
for t in auth[\"data\"][\"refresh_tokens\"]:
    if t.get(\"client_name\") == \"agent-automation\":
        header = base64.urlsafe_b64encode(json.dumps({\"alg\":\"HS256\",\"typ\":\"JWT\"}).encode()).rstrip(b\"=\")
        now = int(time.time())
        payload = base64.urlsafe_b64encode(json.dumps({\"iss\":t[\"id\"],\"iat\":now,\"exp\":now+86400*365}).encode()).rstrip(b\"=\")
        sig_input = header + b\".\" + payload
        sig = base64.urlsafe_b64encode(hmac.new(t[\"jwt_key\"].encode(), sig_input, hashlib.sha256).digest()).rstrip(b\"=\")
        print((sig_input + b\".\" + sig).decode())
        break
'" 2>/dev/null)

エンティティを一覧表示する（ドメイン別）

ssh nuc "curl -s -H 'Authorization: Bearer $TOKEN' http://localhost:8123/api/states" | python3 -c "
import json, sys
states = json.load(sys.stdin)
for s in sorted(states, key=lambda x: x['entity_id']):
    eid = s['entity_id']
    name = s['attributes'].get('friendly_name', '')
    domain = eid.split('.')[0]
    if domain in ('light', 'switch', 'cover', 'media_player', 'fan', 'binary_sensor', 'scene', 'humidifier'):
        print(f'{eid:55s} {name}')
"

必要に応じて domain in (...) フィルターを変更するか、すべてのエンティティを表示するにはフィルターを削除してください。

サービスを呼び出す

ssh nuc "curl -s -X POST -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{\"entity_id\": \"media_player.tv\"}' \
  http://localhost:8123/api/services/media_player/turn_off"

設定フローを開始する

ssh nuc "curl -s -X POST -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{\"handler\": \"spotify\"}' \
  http://localhost:8123/api/config/config_entries/flow"

ヘルパースクリプト（参考）

scripts/ 内のスクリプトは API の使用パターンを確認する参考になりますが、SSH 経由でパイプするか、コマンドに直接記述する必要があります。NUC にはデプロイされていません。

スクリプト	目的
ha-token.sh	認証ストレージから JWT を生成する
ha-api.sh	汎用 API ラッパー
ha-entities.sh	ドメイン別にエンティティを一覧表示する
ha-integrations.sh	設定済みインテグレーションを一覧表示する
ha-call.sh	エンティティに対してサービスを呼び出す
ha-flow.sh	設定フローを管理する（開始／送信）

参考資料

詳しい情報については、以下を参照してください。

ファイル	内容
references/integration-flows.md	インテグレーションごとの設定フローの動作、中止理由、mDNS 検出コマンド
references/default-integrations.md	NixOS の defaultIntegrations リスト — 自動読み込みされるもの、Nix の設定例
references/device-protocols.md	デバイスレジストリからデバイスのプロトコル（Matter/Zigbee/Thread/HomeKit）を特定する方法、ベンダーのモデル名の規則、ZHA 移行の判断ツリー

トークンの生成

HA の長期有効トークンは、/var/lib/hass/.storage/auth にあるトークンごとのキーで署名された HS256 JWT です。scripts/ha-token.sh を使用するか、以下のコマンドをインラインで実行してください。

ssh nuc "sudo bash ha-token.sh"           # uses "agent-automation" token
ssh nuc "sudo bash ha-token.sh my-token"  # use a different token name

まだトークンがない場合は、HA UI から作成してください。 プロフィール → セキュリティ → 長期有効アクセストークン → トークンを作成

確認方法：curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8123/api/ → {"message":"API running."}

API クイックリファレンス

すべてのリクエストは、Authorization: Bearer $TOKEN を付けて http://127.0.0.1:8123 に送信します。

アクション	メソッド	エンドポイント	ボディ
ヘルスチェック	GET	/api/	—
HA 設定	GET	/api/config	—
状態一覧	GET	/api/states	—
エンティティの状態を取得	GET	/api/states/{entity_id}	—
エンティティの状態を設定	POST	/api/states/{entity_id}	{"state": "...", "attributes": {...}}
イベントを発生させる	POST	/api/events/{event_type}	{...event_data}
サービスを呼び出す	POST	/api/services/{domain}/{service}	{"entity_id": "..."} + サービスデータ
サービス一覧	GET	/api/services	—
設定エントリー一覧	GET	/api/config/config_entries/entry	—
設定フローを開始	POST	/api/config/config_entries/flow	{"handler": "domain"}
フローのステップを送信	POST	/api/config/config_entries/flow/{flow_id}	ステップ固有のデータ
フローを中止	DELETE	/api/config/config_entries/flow/{flow_id}	—
設定エントリーを削除	DELETE	/api/config/config_entries/entry/{entry_id}	—
アプリの認証情報を追加	POST	/api/config/application_credentials	{"domain":"...","client_id":"...","client_secret":"..."}
テンプレートをレンダリング	POST	/api/template	{"template": "{{ states('...') }}"}
設定をチェック	POST	/api/config/core/check_config	—

主なワークフロー

設定フロー（OAuth 以外）

ha-flow.sh start cast           # auto-discovery, usually creates entry immediately
ha-flow.sh start matter         # returns form → submit with URL
ha-flow.sh submit <flow_id> '{"url":"ws://localhost:5580/ws"}'

OAuth 統合（Spotify、Google など）

1. 先にアプリの認証情報を登録します（中止理由：missing_credentials）
2. 設定フローを開始します。ユーザー向けの認証 URL が返されます

ha-api.sh POST /api/config/application_credentials \
  '{"domain":"spotify","client_id":"ID","client_secret":"SECRET"}'
ha-flow.sh start spotify

統合ごとの詳細については、references/integration-flows.md を参照してください。

NixOS のコンテキスト

• 認証情報の保存先：/var/lib/hass/.storage/auth
• API：http://127.0.0.1:8123（ローカルホストのみ）、Tailscale serve 経由の HTTPS
• 公開 URL：https://homeassistant.cinnamon-rooster.ts.net/
• defaultIntegrations は入力ヘルパー、自動化、シーン、スクリプトなどを自動的に読み込みます。references/default-integrations.md を参照してください