Home Assistant Refresh Key Expired

Symptom:

On your iPhone you open the Home Assistant Companion App, but it shows a blank screen and no controls for fixing it. I suspect that Android has the same issue but I didn't actually see it happen.

What's happening:

The API key (Refresh Key) for the iPhone's persistent session probably expired. Alternatively, I've been doing some network improvements and if the refresh key is tied to the client's IP or MAC address, it's possible that it could be considered corrupt.

How to fix:

Log in to the server's web GUI, in my case http://dragon.cft.ca.us:8123/ (insecure, but TLS is now available and I should set that up). Authenticate as the user. On the resulting dashboard, in its sidebar (turn on if you turned it off), look at the bottom (scroll if necessary) for the line item for your identity, like a profile. Open it. Switch to the Security tab. Identify and delete the Refresh Key for the persistent session on your iPhone. Log out (on the General tab).

Now on the iPhone (Android should work identically): Open the Home Assistant Companion App. No more blank screens. It searches for the server, finding it (click on the row), and explains that the server rejected the credential that you just deleted, so you have to log in again (click). Give your loginID and password. The app authenticates successfully, obtains a new Refresh Key (silently), and displays Home Assistant's dashboard.

If you're using a password manager such as Bitwarden, click in the loginID (user) field and the keyboard will appear. Click on "Passwords" in its auto-completion row. My wife has Face ID registered, which lets her into Bitwarden; otherwise struggle with the vault password. Search for your loginID, find the Home Assistant login card, and click on the auto-fill icon.