# Access and security

> Password, login on the deck, API keys, lockout, HTTPS and CORS.

Source: https://deckconnector.com/docs/security/

## 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](https://deckconnector.com/demo/#access)).

Before setup, a browser gets in without the password for a short time, see [First setup](https://deckconnector.com/docs/first-setup/#in-the-browser). 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](https://deckconnector.com/docs/home-assistant/) use an API key. Make one under **Access › API access**. It shows only once.

```bash
curl -H 'Authorization: Bearer KEY' http://192.168.1.50/api/status
```

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>.local` and `localhost`, 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/ca` gives the CA, `GET /api/cert` the 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](https://deckconnector.com/docs/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 `Host` header and add the client to `X-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.

Next: [API](https://deckconnector.com/docs/api/), [Home Assistant](https://deckconnector.com/docs/home-assistant/)
