Bashio: services, discovery, auth, and ingress

These functions wrap the services, discovery, auth, and ingress endpoints of the Supervisor API. The function lists on this page are generated from the docblocks in the source of Bashio. The descriptions are the ones in the source, so some still say "addon" where this site says app.

They need the matching permission in config.yaml: services to use or offer a service, discovery to send discovery messages, and auth_api: true to check credentials. Some auth and ingress functions need more, see their sections. How these fit together is in Share services and discover integrations and Add a web interface with ingress.

#!/command/with-contenv bashio

if bashio::services.available 'mqtt'; then
  host=$(bashio::services 'mqtt' 'host')
  port=$(bashio::services 'mqtt' 'port')
  bashio::log.info "Using the MQTT broker at ${host}:${port}"
fi

Use a service like MQTT or MySQL, or offer one, from /services. Source: lib/services.sh.

• bashio::services: Get configuration object or configuration options from a service.
  • $1: Service name
  • $2: Config option to get (optional)
• bashio::services.available: Check if this service is available.
  • $1: Service name
• bashio::services.publish: Publish a new configuration object for this service.
  • $1: Service name
  • $2: Configuration object (JSON)
• bashio::services.delete: Deletes configuration object for this service.
  • $1: Service name

Send discovery messages to Home Assistant, at /discovery. Source: lib/discovery.sh.

• bashio::discovery: Publish a new configuration object for discovery.
  • $1: Service name
  • $2: Configuration object (JSON)
• bashio::discovery.delete: Deletes configuration object for this discovery.
  • $1: Discovery UUID

Check the credentials of Home Assistant users, list the users, and reset a password, from /auth. Only bashio::auth works with auth_api: true. The others are account administration and need hassio_api: true with a role: hassio_role: admin to list users or reset a password, and manager or admin to clear the cache. Source: lib/auth.sh.

• bashio::auth: Authenticates a Home Assistant user against the Supervisor auth backend. The Supervisor signals the outcome via the HTTP status: a valid set of credentials returns 200, while invalid credentials return 401. That maps directly onto the return code of bashio::api.supervisor, so a successful call means the user authenticated. The password is never logged: a placeholder is traced instead and the request body is routed through api.supervisor, which keeps POST bodies out of the process list and the trace log.
  • $1: Username of the Home Assistant user
  • $2: Password of the Home Assistant user
• bashio::auth.list: Lists the Home Assistant users known to the Supervisor auth backend.
• bashio::auth.reset: Resets the password of a Home Assistant user. The password is never logged: a placeholder is traced instead and the request body is routed through api.supervisor, which keeps POST bodies out of the process list and the trace log.
  • $1: Username of the Home Assistant user
  • $2: New password for the Home Assistant user
• bashio::auth.cache.reset: Clears the Supervisor auth cache.

Ingress panels and sessions, from /ingress. Listing the panels needs hassio_api: true with hassio_role: admin. Creating and validating sessions only works for Home Assistant Core: with the token of an app, these calls fail. For the ingress port and URL of your own app, use the bashio::app.ingress_* functions on the apps page. Source: lib/ingress.sh.

• bashio::ingress.panels: Returns a JSON object with the available ingress panels.
  • $1: Cache key to store results in (optional)
  • $2: jq Filter to apply on the result (optional)
• bashio::ingress.session: Creates a new ingress session and returns its session identifier.
• bashio::ingress.validate_session: Validates an ingress session and extends how long it stays valid.
  • $1: Ingress session identifier