Skip to content

v4.2.0: API tokens in the user menu

Choose a tag to compare

@raphael1688 raphael1688 released this 08 Nov 02:59
· 6 commits to main since this release

✨ API tokens in the user menu

Scripts can now get a longer-lived API token from the interface. Open the user
menu → "API Tokens", confirm your password (and two-factor code, when
enabled), choose how long the token lasts — 1 day, 7 days, 30 days, 90 days,
1 year, 2 years or 3 years
— and copy the token. It is shown once.

curl -H "Authorization: Bearer <token>" http://<home-assistant>:81/api/nginx/proxy-hosts

How it works

  • New patch 0005-Patch-add-API-tokens-to-the-user-menu: POST /api/tokens
    and POST /api/tokens/2fa accept an optional expiry from the list above.
    Logins without it still last 1 day.
  • No database changes, so the patch can be dropped cleanly if upstream ships
    stored tokens (NginxProxyManager/nginx-proxy-manager#5975).

🔒 Security

  • GET /api/tokens (token refresh) no longer accepts ?expiry=. Upstream let
    any logged-in session swap its token for one of any lifetime without the
    password. A refresh now always lasts 1 day; longer tokens need the password.

ℹ️ Good to know

  • Tokens aren't stored, so they can't be listed or revoked one by one.
    Changing the user's password ends every token issued before it, and
    disabling the user ends all of its tokens.
  • A token acts as its user, with that user's permissions. For scripts, create
    a dedicated user with only the permissions it needs.
  • A 2- or 3-year token can expire a few hours before the displayed time
    (upstream computes the two slightly differently).

✅ Verification

Built and tested on real aarch64 hardware running Home Assistant OS: a
token from the user menu authenticates API calls on port 81, a wrong password
shows an error without logging out, and login/logout and the sidebar still
work.