Google Home API

Tools exposes a permission-gated Google Home integration for Home Graph requests, spoken broadcasts on Google Home or Nest speakers, and mobile push notifications.

Access model

• API routes are under /api/google-home/*.
• Requires an authenticated user with google-home.use permission (admins are allowed).
• User-facing administration is available at /admin/google-home.
• The dashboard and Services catalogue link to the same Google Home / Nest area when the user has permission.
• Broadcast and Home Graph operations additionally require a Google Home profile explicitly owned by the current user.

The google-home.use permission does not grant access to the platform owner's Home Assistant or Home Graph credentials. Credential ownership is enforced separately.

Credential ownership and .env

Google Home, Home Graph, and Home Assistant data from .env is never a global fallback. It must be assigned to exactly one Tools user ID:

GOOGLE_HOME_OWNER_USER_ID=1

If GOOGLE_HOME_OWNER_USER_ID is empty or 0, the environment profile's Google OAuth, Home Graph, and Home Assistant credentials cannot be used by any user.

For the assigned user, .env is authoritative and takes precedence over any database profile. Other users can create their own credentials at /admin/google-home; their Google OAuth client secret, Home Graph credentials, and Home Assistant token are encrypted and associated with their own user ID.

This prevents a user with google-home.use from accidentally accessing another user's speakers, Home Graph, or Home Assistant instance.

Setup and authentication map

The Google Home area contains separate integrations that use separate credentials. Speaker broadcast, Home Graph, mobile push, and a future direct Cloud-to-cloud integration are not one shared OAuth flow.

Speaker broadcast: Home Assistant authenticates with Google

Tools does not authenticate directly with Google to speak on Google Home or Nest speakers. The Google OAuth flow belongs to Home Assistant's Google Assistant SDK integration.

1. Enable Google Assistant API in Google Cloud.
2. Create an OAuth Client ID of type Web application.
3. Use the literal URI https://my.home-assistant.io/redirect/oauth as the Authorized redirect URI.
4. Add the Google Assistant SDK integration in Home Assistant and authorize the Google account.
5. Verify that notify.google_assistant_sdk is available in Home Assistant.

Direct links:

• Google Assistant API: https://console.developers.google.com/apis/api/embeddedassistant.googleapis.com/overview
• Google Auth Platform / Clients: https://console.cloud.google.com/auth/clients
• Home Assistant Google Assistant SDK: https://www.home-assistant.io/integrations/google_assistant_sdk/

For an environment-owned profile, the OAuth client may be documented alongside the profile:

GOOGLE_HOME_ASSISTANT_OAUTH_LABEL="Google Home"
GOOGLE_HOME_ASSISTANT_OAUTH_CLIENT_ID=
GOOGLE_HOME_ASSISTANT_OAUTH_CLIENT_SECRET=
GOOGLE_HOME_ASSISTANT_OAUTH_REDIRECT_URI=https://my.home-assistant.io/redirect/oauth

These variables are separate from GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI, which are used for ordinary Google sign-in to Tools.

Tools authenticates with Home Assistant

Tools calls the Home Assistant REST API using a long-lived Home Assistant access token.

For the environment owner:

GOOGLE_HOME_BROADCAST_DRIVER=home_assistant
GOOGLE_HOME_HOME_ASSISTANT_URL=https://your-home-assistant.example
GOOGLE_HOME_HOME_ASSISTANT_TOKEN=YOUR_LONG_LIVED_ACCESS_TOKEN
GOOGLE_HOME_HOME_ASSISTANT_DOMAIN=notify
GOOGLE_HOME_HOME_ASSISTANT_SERVICE=google_assistant_sdk
GOOGLE_HOME_HOME_ASSISTANT_TIMEOUT=15
GOOGLE_HOME_BROADCAST_DEFAULT_TARGETS=

Other users store the equivalent URL/token in their personal Google Home profile. The Home Assistant token is encrypted in google_home_profiles, and the Google OAuth client secret is encrypted through oauth_provider_apps.

Home Assistant authentication documentation:

• https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token

Future direct Google Home -> Tools integration

A future integration where Google Assistant sends SYNC, QUERY, EXECUTE, and DISCONNECT intents directly to Tools is a separate Google Home Cloud-to-cloud integration. That flow requires a Google Home Developer Console project and OAuth 2.0 account linking implemented by Tools.

Official references:

• https://console.home.google.com/
• https://developers.home.google.com/project/create
• https://developers.home.google.com/cloud-to-cloud/primer/account-linking
• https://developers.home.google.com/cloud-to-cloud/project/authorization

This direct account-linking flow is not required for the Home Assistant speaker broadcast transport.

Broadcast a spoken message

The normal administration UI at /admin/google-home includes a dedicated broadcast form, so users do not need to write JSON for normal speaker messages.

The API still uses the generic request endpoint. Before sending anything, Tools resolves the authenticated user's profile. If no profile belongs to that user, the request returns 403; platform .env credentials are not used as a global fallback.

POST /api/google-home/request

{
  "endpoint": "broadcast",
  "payload": {
    "message": "The forum server is not responding.",
    "target": ["office"]
  }
}

target is optional and contains Google Assistant room names. Omit it to use the profile's default targets, or all available speakers when no defaults are configured.

Use dry_run to validate payload normalization without contacting Home Assistant:

{
  "endpoint": "broadcast",
  "payload": {
    "message": "Configuration test.",
    "dry_run": true
  }
}

A successful response contains endpoint: "broadcast", the selected driver, profile source (environment or database), and HTTP status information. Broadcast requests do not trigger a duplicate mobile push notification.

Broadcast configuration

The environment-owned user can use fake mode without Home Assistant:

GOOGLE_HOME_OWNER_USER_ID=1
GOOGLE_HOME_BROADCAST_DRIVER=fake

Real speaker broadcasts require that assigned user's Home Assistant URL/token and the home_assistant driver.

The Home Assistant instance must have the Google Assistant SDK integration configured. Tools calls the user-owned Home Assistant profile's service API and normally invokes notify.google_assistant_sdk.

Personal profiles for other users

When a user is not the user referenced by GOOGLE_HOME_OWNER_USER_ID, the Google Home page shows the My Google Home credentials form. The user can provide:

• their own Google OAuth Client ID and Client Secret
• redirect URI
• an optional personal Home Graph API key and/or bearer token
• their own Home Assistant URL and long-lived token
• broadcast driver
• Home Assistant domain/service
• default rooms/targets

Secrets are never returned in plaintext from the status UI. Leaving an existing secret/token field empty when saving retains the encrypted stored value.

Home Graph endpoints

Home Graph is separate from the speaker transport but follows the same ownership rule. Query/request-sync resolves only the authenticated user's assigned profile. A missing profile returns 403; a profile without an API key or bearer returns 503.

Current Google documentation is available at:

• https://developers.home.google.com/reference/home-graph/rest
• https://developers.home.google.com/cloud-to-cloud/integration/request-sync

POST /api/google-home/request

{
  "endpoint": "v1/devices:query",
  "payload": {
    "agentUserId": "demo-user",
    "inputs": []
  }
}

POST /api/google-home/devices/query

Convenience endpoint for state queries.

POST /api/google-home/devices/request-sync

Convenience endpoint for sync requests.

Mobile push endpoints

Mobile push is separate from Home control. FCM transport is platform-level, while destination push tokens are already associated with the current Tools user.

POST /api/google-home/push/tokens/register

{
  "token": "fcm-device-token",
  "platform": "android",
  "device_label": "Example phone"
}

GET /api/google-home/push/tokens

List active push tokens for the current user.

DELETE /api/google-home/push/tokens/{tokenId}

Deactivate a registered push token for the current user.

POST /api/google-home/push/test

Send a test push to all active tokens for the current user.

FCM HTTP v1 configuration

The mobile push service uses FCM HTTP v1. The legacy server-key endpoint is not used.

GOOGLE_FCM_PROJECT_ID=example-project
GOOGLE_FCM_SERVICE_ACCOUNT_JSON=YOUR_SERVICE_ACCOUNT_JSON_PATH
GOOGLE_FCM_ACCESS_TOKEN=
GOOGLE_FCM_V1_ENDPOINT=https://fcm.googleapis.com/v1/projects/{project_id}/messages:send
GOOGLE_FCM_VALIDATE_ONLY=false
GOOGLE_FCM_TIMEOUT=15

References:

• https://firebase.google.com/docs/cloud-messaging/send/v1-api
• https://console.firebase.google.com/

GOOGLE_FCM_PROJECT_ID may be omitted when the service account JSON contains project_id. GOOGLE_FCM_ACCESS_TOKEN is intended only for short-lived manual tests.

The old settings GOOGLE_FCM_SERVER_KEY and GOOGLE_FCM_ENDPOINT are no longer used.

Home Graph configuration

For the environment-owned profile:

• GOOGLE_HOME_API_BASE_URL (default https://homegraph.googleapis.com)
• GOOGLE_API_KEY (optional)
• GOOGLE_HOMEGRAPH_BEARER (optional)
• GOOGLE_HOME_TIMEOUT (default 15)

These values follow GOOGLE_HOME_OWNER_USER_ID and cannot be used by other Tools users. Personal profiles store the equivalent API key/bearer encrypted in google_home_profiles.

At least one Home Graph credential is required for device query and request-sync calls. It is not required for the broadcast transport.