How Does Home Assistant Authenticate Local and Remote Sessions?
Home Assistant does not normally create one authentication system for the LAN and another for remote access. The user authorizes against the Home Assistant instance, applications receive tokens, and those tokens authenticate API or WebSocket sessions whether the request arrives through a local URL, Home Assistant Cloud, a VPN, or a reverse proxy.
What changes between local and remote use is primarily the network path: DNS, TLS, proxying, tunneling, and public reachability. Keeping route and identity separate is important because a broken remote URL can look like a login problem even when the Home Assistant user's credentials and tokens are still valid.
Applications Authorize Once and Receive Access and Refresh Tokens
Home Assistant's application authentication flow produces an authorization code and then an access token plus a refresh token. The short-lived access token is used for API calls; the refresh token allows the application to request a new access token without asking the user to log in for every session.
The current Authentication API documents the authorization, access-token, refresh-token, and HTTP Bearer-token flow. When an access token becomes invalid, an HTTP API request returns 401 and the client should refresh or re-authorize.
This separates a user's long-term authorization from the short lifetime of a particular API credential.
WebSocket Sessions Authenticate Before Live State Streaming Begins
The frontend and many applications keep a WebSocket open so Home Assistant can stream state and event updates without polling the server for every change.
Home Assistant's WebSocket API defines an explicit authentication phase: the server sends auth_required, the client returns an access token, and only an auth_ok response moves the connection into the command phase.
An invalid token ends that session. A network timeout before the authentication exchange begins is a different failure from an auth_invalid response after the server has received the token.
Remote Access Changes How the Client Reaches Home Assistant
By default Home Assistant is local. Remote access can be provided through Home Assistant Cloud, a VPN, a reverse proxy, or a deliberately secured direct path. Each option changes routing and exposure, but the destination is still the same Home Assistant instance.
The current remote-access guide distinguishes Cloud, VPN, reverse proxy, and port-forwarding routes. Reverse proxies also introduce a trust boundary because Home Assistant must know which proxy is allowed to supply forwarded request information.
This is why a router, DNS, certificate, or proxy change can break remote access without requiring users to be recreated.
Local and Remote Sessions Can Have Different Network Risk
A LAN connection may remain inside a trusted home network while a remote connection crosses the public internet or an overlay network. Secure remote design therefore adds encryption, proxy hardening, VPN policy, and multi-factor authentication around the same Home Assistant account system.
Do not interpret “same authentication model” as “same network exposure.” A direct public port, a managed cloud tunnel, and a private VPN present different attack surfaces even when all three ultimately submit Home Assistant access tokens.
The ZimaSpace remote-access security guide provides the broader network boundary for deciding which path should carry those authenticated sessions.
Separate Route Failures From Authentication Failures
| Symptom | Likely layer | First distinction |
|---|---|---|
| Remote hostname does not resolve | DNS / route | Authentication has not started |
| TLS or proxy error before login | Remote entry path | Test direct local access |
| HTTP 401 from Home Assistant API | Token/authentication | Refresh or re-authorize client |
| WebSocket returns auth_invalid | Token/authentication | Validate client authorization |
| Local works, remote route fails | DNS/VPN/proxy/NAT | Do not reset users first |
The clean mental model is identity first, session token second, network route third. Local and remote clients may enter through very different network paths, but they still need a valid Home Assistant authorization once they reach the instance.
FAQ
Does remote Home Assistant access require a different password or account?
No. Remote clients normally authenticate to the same Home Assistant user system. The remote method changes how the client reaches the instance, not which user database owns the account.
Should I delete tokens when only the remote URL stops working?
Not as the first step. First prove that DNS, VPN, proxy, TLS, or NAT reaches Home Assistant. Reset or re-authorize tokens when Home Assistant itself rejects authentication, not merely because the network path is unavailable.
Recommended products
Tech & AI HUB
More to Read
Runtime State vs Persistent State in Home Assistant: What Must Survive Restart?
Home Assistant does not persist every live value; config, registries, selected restored states, history, and deployment data play different restart roles.
Why Can Home Assistant History Queries Slow as Recorder Data Grows?
Recorder growth can raise History query cost when the requested range touches more rows, cache misses increase, or storage and index work become slower.
Why Does Home Assistant Rebuild Different State After a Container Restart?
Container restart does not equal state loss: Home Assistant rebuilds runtime state from persistent config, integrations, registries, and external sources.
