# Bashio: services, discovery, auth, and ingress

> Bashio functions to use and offer services like MQTT, send discovery messages to Home Assistant, check user credentials, and work with ingress.

Source: https://contributors.home-assistant.io/apps/bashio/services/

<!-- Generated by `pnpm bashio` from scripts/bashio/services.md. Edit that file, not this one. -->

These functions wrap the [services, discovery, auth, and ingress endpoints](https://contributors.home-assistant.io/apps/supervisor-api/services/) 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](https://contributors.home-assistant.io/apps/guides/services-discovery/) and [Add a web interface with ingress](https://contributors.home-assistant.io/apps/guides/ingress/).

```bash
#!/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
```

## Services

Use a service like MQTT or MySQL, or offer one, from `/services`. Source: [`lib/services.sh`](https://github.com/hassio-addons/bashio/blob/main/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

## Discovery

Send discovery messages to Home Assistant, at `/discovery`. Source: [`lib/discovery.sh`](https://github.com/hassio-addons/bashio/blob/main/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

## Auth

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](https://contributors.home-assistant.io/apps/guides/security/#api-roles): `hassio_role: admin` to list users or reset a password, and `manager` or `admin` to clear the cache. Source: [`lib/auth.sh`](https://github.com/hassio-addons/bashio/blob/main/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

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](https://contributors.home-assistant.io/apps/bashio/apps/). Source: [`lib/ingress.sh`](https://github.com/hassio-addons/bashio/blob/main/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