Services, discovery, auth, and ingress endpoints

These endpoints are how apps work together, and with Home Assistant. Most of them need no hassio_api permission: what your app may do is set in its config.yaml instead, with services, discovery, and auth_api. See services and discovery for how to use them in your app.

A service is something one app provides and other apps use, like an MQTT broker. The providing app registers its connection details, and apps that need the service read them, so users do not have to type in a host name and password.

There are two services: mqtt and mysql.

Your app needs the service in the services option of its configuration. What the Supervisor checks:

• Reading and registering work with any role for the service: want, need, or provide. Registering fails while another app is registered as the provider.
• Removing a registration needs <service>:provide.

In the configuration, provide is the role meant for the app that registers.

Returns the connection details the provider registered. Fails when no app provides the service.

{
  "addon": "core_mosquitto",
  "host": "core-mosquitto",
  "port": 1883,
  "ssl": false,
  "protocol": "3.1.1",
  "username": "addons",
  "password": "Ahng5Ohghahy"
}

Registers your app as the MQTT broker.

Registers your app as the MySQL server.

Removes the registration of the service. Call it from the providing app when it stops providing the service. The Supervisor does not check which app made the registration: it removes the current one.

With discovery, your app tells Home Assistant it is running, and how to reach it. Home Assistant then offers to set up the matching integration. Your app may only send discovery for the integrations listed in the discovery option of its configuration.

{
  "service": "mqtt",
  "config": {
    "host": "core-mosquitto",
    "port": 1883
  }
}

The response has the uuid of the message. Keep it, so you can remove the message later.

Removes a discovery message. Your app can only remove its own messages.

With auth_api: true in its configuration, your app can check the user name and password of a Home Assistant user. Use it to let users log in to your app with their Home Assistant account.

auth_api only covers /auth itself. The other auth endpoints are account administration, and need hassio_api: true with a role: admin for /auth/list and /auth/reset, manager or admin for /auth/cache.

Checks a user name and password. Send them in one of three ways:

• An Authorization: Basic header. Send your token in X-Supervisor-Token then.
• A JSON body with username and password.
• A form body (application/x-www-form-urlencoded) with username and password.

Returns success when the credentials are right, and 401 when they are not. The Supervisor caches correct credentials for a while, so Home Assistant does not get a request for every login.

Any Authorization header counts as the first way, so the Supervisor tries to read it as Basic credentials. Send your token in X-Supervisor-Token here, not in Authorization: Bearer:

curl -sSL -X POST \
  -H "X-Supervisor-Token: ${SUPERVISOR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"username": "jane", "password": "secret"}' \
  http://supervisor/auth

Returns the users of Home Assistant that have a user name.

Clears the cache of correct credentials.

Ingress shows the web interface of your app inside Home Assistant. The Supervisor proxies the requests, so your app does not need its own login or open port. Home Assistant Core uses these endpoints to set up ingress sessions. Your app does not call them itself.

Returns the new session as session. The browser sends it to the Supervisor in the ingress_session cookie.

Returns success when the session is valid, and 401 when it is not.