Access and security
Password, login on the deck, API keys, lockout, HTTPS and CORS.
Password
The web UI has one user, admin. On its first start the connector makes a random password and shows it in the deck menu. Set your own (6 to 23 characters) in the setup or under Access (demo).
Before setup, a browser gets in without the password for a short time, see First setup. A factory reset opens it again.
A new password restarts the connector and ends every session. A session ends after 12 hours without use, on logout, and on a power cut.
Lost password
The login page offers three ways. Each needs someone at the deck, and presses sent over the API never count.
| Way | On the deck |
|---|---|
| Ask the deck | Tap Accept within 60 s |
| Password on the deck | The password shows for 30 s |
| Reset | Tap Reset twice within 60 s. Every setting is gone |
When one of these ends without Accept, the same address can start it again only after one minute. The login page shows how long. All IPv6 addresses with the same first half (/64) count as one address.
Lockout
- After five wrong passwords from one address, that address waits a few seconds, up to a minute.
- After 30 wrong passwords in one minute from all addresses, everyone waits until the minute ends, except the last four addresses that logged in.
- An API key is never locked out.
API keys
Scripts and Home Assistant use an API key. Make one under Access › API access. It shows only once.
curl -H 'Authorization: Bearer KEY' http://192.168.1.50/api/statusFour levels, each includes the one above. open: everyone. control: the password, or an API key with control or full access. full: the password, or a full access key. admin: the password only.
- openEveryoneLogin, certificate, lost password help, first setup
- controlPassword, control or full keyStatus, deck picture, presses, menu, metrics
- fullPassword, full keySettings, restart, updates, slots, log, pairing, Wi-Fi
- adminPassword onlyPassword, API keys, backup, crash report, own certificate, factory reset
A key has Control (control) or Full access (full). Up to 8 keys exist. Deleting one ends it at once. A new key with the same name replaces the old one. The connector keeps only a hash, and a backup never holds a key. Home Assistant deletes its own key when you remove the integration.
HTTPS
The connector serves port 80 and HTTPS on 443. Its certificate comes from its own CA, which the connector makes on its first start. Trust the CA once on each device under Access › HTTPS. Then no browser warns at https://<name>.local.
- The CA vouches only for
<name>.localandlocalhost, never for another name or an IP address. - The certificate is renewed 30 days before it runs out. The fingerprint changes each time, the CA stays.
- A new name gets a new CA. Trust it again on each device.
- A factory reset deletes the CA.
GET /api/cagives the CA,GET /api/certthe current certificate as PEM.- HTTPS only turns plain HTTP off. The start page redirects, every other request over HTTP gets 403. While the setup Wi-Fi is open, HTTP stays on. Home Assistant needs plain HTTP and stops working.
- You can upload your own certificate and key as PEM. A key with a password is refused.
Passkeys
A passkey logs you in with your fingerprint, face or device PIN. Add one under Access › Passkeys.
- It needs HTTPS without a warning and a name, like
https://deckconnector-a1b2c3.local. Trust the CA first, or upload a certificate for your own name. - A passkey works only at the name it was made on. After a rename, add it again.
- Up to 8 passkeys. The password keeps working. A factory reset deletes all passkeys.
Behind a reverse proxy
A proxy such as Caddy can serve the connector under its own name. Then every request comes from the proxy's address. Enter that address under Access › HTTPS › Reverse proxy. The connector then takes the client from the last entry of X-Forwarded-For. It uses it for the lockout, for passkeys and for the login question on the deck.
- The connector reads the header only from that one address. From anyone else it ignores it.
- The proxy must keep the
Hostheader and add the client toX-Forwarded-For. Caddy does both by default. - Through the proxy, the first-browser setup and Companion's Discover do not work.
Setup Wi-Fi
A browser on the setup Wi-Fi needs no web password. Only the deck shows the Wi-Fi password, so you must be at the deck to join. Only phones on the setup Wi-Fi get the sign-in page and the connector's own DNS answers. The LAN never does.
CORS
A web page from another origin may call the API with an API key when its origin is in Allowed web pages. Empty by default. Cookies never work across origins.