Supervisor External API Access

Installation Home Assistant OS
#1

Alright, I’m a couple days in of trying to figure this out. Here’s where I’m at:

Documentation Link

REST API

Supervisor API via SSH

  • Downloaded “Terminal & SSH” Add-ons & “Open Web UI”
  • Run curl -sSL -H "Authorization: Bearer $SUPERVISOR_TOKEN" http://supervisor/supervisor/ping
  • Success

Supervisor API via Externally

  • Obtained SUPERVISOR_TOKEN
  • No clue what web address is locally available for Supervisor. This is where I need help. I’m expecting to be able to run " http://SOME_SUPERVISOR_IP/supervisor/ping"
Best strategy for copying HA backups to a different location
#2

None. Supervisor’s API is not exposed externally. It is only accessible from within the docker network. This is by design, it is not intended to be a public facing API.

If you’re a developer trying to make additions to supervisor then you can temporarily expose its API externally on a dev system by adding the remote API addon. This addon will print you an auth token for supervisor in its logs. Then it will listen on a port on the host and proxy requests made through it to the supervisor API.

But this addon is only for development. It is not an LLAT, the token will change every time it restarts. If you are trying to do this on a production system then consider instead writing your own addon with an auth mechanism that you control and exposing specific functionality you need in an API. That addon can then proxy those requests to the supervisor API.

Although I would be curious to hear your use cases here. I am one of the devs for supervisor. Is it just the ping API for some kind of external healthcheck tool or is there a bigger plan?

Disclosure: Supervisor security vulnerability
How to call supervisor API correctly
#3

Thanks for the reply, this is good information I wasn’t aware about.

The use case, at least for me, is that I’m creating an frontend integration platform and was wanting to provide more interactions and display more data than the REST API can provide.

If creating a companion addon for the frontend integration is the way to go, then I guess that’s my new direction!

#4

Ah. So for frontend you should have some options. I actually don’t know frontend that well but you should take a look at what the settings menus do. For example the network panel is communicating with supervisor since Supervisor has the APIs for getting and updating network info from the host. It is proxying its requests through HA somehow, I would guess via the websockets API.

If you write a custom frontend plugin you should be able to do the same I would think. Since HA is a container in the same network as supervisor it can be your proxy in this case as long as it has exposed the options you’re looking for. If its missing some then you might need to make your own addon proxy for those.

1 Like
#6

@CentralCommand up until recently, the supervisor API was exposed via the /hassio subpath of the regular REST API:

http://hass.url/api/hassio

We’re primarily using this external endpoint to speed up Add-on development when we are debugging the Add-on outside of Home Assistant. Is there a particular reason this API endpoint was deprecated?

We’re mostly just using it for fingerprinting, eg. for authorizing a unique ‘instance’ even across a fresh reinstall, so it’s not the end of the world for development purposes, but I was surprised to see the endpoint disappear. If I remember correctly, one of the key pieces of data we were using for identifying a unique instance was dropped from the endpoint at some point anyway, so most users probably fallback to a more generic ID method anyway at this point.

#7

We where using the external API to monitor multiple instances of HA remotely, perform push upgrades and make daily backups from a central server and dashboard.

The add-on doesn’t work for us as the TOKEN is randomly generated on reboot.