hass-config-flow

Home Assistant REST API

Docs: https://developers.home-assistant.io/docs/api/rest/

NixOS extraComponents bundles integration code, but config-flow-only integrations (Spotify, Matter, HomeKit Controller, Cast, etc.) require the REST API or UI to complete setup.

hass-cli (preferred for inspection/simple calls)

home-assistant-cli is installed on the NUC. Prefer it over raw curl for entity listing, service calls, device/area management, and event watching.

# 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'])"

Note: hass-cli info is broken on current HA (deprecated endpoint). All other commands work.

Use raw curl (below) for config flows, app credentials, and anything hass-cli doesn't cover.

Querying the API (inline SSH)

Scripts in scripts/ exist but are local — they can't be referenced by path on the NUC. Use inline SSH commands instead.

Get a token

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)

List entities (by domain)

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}')
"

Change the domain in (...) filter as needed, or remove it for all entities.

Call a service

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"

Start a config flow

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"

Helper scripts (reference)

Scripts in scripts/ are useful as reference for the API patterns but must be piped via SSH or inlined — they aren't deployed to the NUC.

Script	Purpose
ha-token.sh	Generate JWT from auth storage
ha-api.sh	General-purpose API wrapper
ha-entities.sh	List entities by domain
ha-integrations.sh	List configured integrations
ha-call.sh	Call a service on an entity
ha-flow.sh	Manage config flows (start/submit)

References

Read these for detailed information:

File	Contents
references/integration-flows.md	Per-integration config flow behavior, abort reasons, mDNS discovery commands
references/default-integrations.md	NixOS defaultIntegrations list — what's auto-loaded, Nix config examples
references/device-protocols.md	Identify device protocol (Matter/Zigbee/Thread/HomeKit) from device registry; vendor model-name conventions; decision tree for ZHA migration

Token generation

HA long-lived tokens are HS256 JWTs signed with a per-token key in /var/lib/hass/.storage/auth. Use scripts/ha-token.sh or inline:

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

If no token exists yet, create via HA UI: Profile → Security → Long-Lived Access Tokens → Create Token

Verify: curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8123/api/ → {"message":"API running."}

API quick reference

All requests to http://127.0.0.1:8123 with Authorization: Bearer $TOKEN.

Action	Method	Endpoint	Body
Health check	GET	/api/	—
HA config	GET	/api/config	—
List states	GET	/api/states	—
Get entity state	GET	/api/states/{entity_id}	—
Set entity state	POST	/api/states/{entity_id}	{"state": "...", "attributes": {...}}
Fire event	POST	/api/events/{event_type}	{...event_data}
Call service	POST	/api/services/{domain}/{service}	{"entity_id": "..."} + service data
List services	GET	/api/services	—
List config entries	GET	/api/config/config_entries/entry	—
Start config flow	POST	/api/config/config_entries/flow	{"handler": "domain"}
Submit flow step	POST	/api/config/config_entries/flow/{flow_id}	step-specific data
Abort flow	DELETE	/api/config/config_entries/flow/{flow_id}	—
Delete config entry	DELETE	/api/config/config_entries/entry/{entry_id}	—
Add app credentials	POST	/api/config/application_credentials	{"domain":"...","client_id":"...","client_secret":"..."}
Render template	POST	/api/template	{"template": "{{ states('...') }}"}
Check config	POST	/api/config/core/check_config	—

Key workflows

Config flow (non-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 integrations (Spotify, Google, etc.)

1. Register app credentials first (abort reason: missing_credentials)
2. Start config flow — returns auth URL for user

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

See references/integration-flows.md for per-integration details.

NixOS context

• Auth storage: /var/lib/hass/.storage/auth
• API: http://127.0.0.1:8123 (localhost only), HTTPS via Tailscale serve
• Public URL: https://homeassistant.cinnamon-rooster.ts.net/
• defaultIntegrations auto-loads input helpers, automation, scene, script, etc. — see references/default-integrations.md