Home Assistant long-lived access tokens: create one, why it must be admin, and “it works but shows nothing”

The short answer

A long-lived access token is a password substitute for apps and scripts: you create it in your Home Assistant profile, on the Security tab, under Long-lived access tokens, and Home Assistant shows it only once. It is valid for 10 years. Some apps need a token from an administrator, because parts of the API, such as /api/template, refuse every other user with a 401.

The rest of this article goes through each piece: what the token is, where to find it, how to copy it without breaking it, why the admin question matters, how to test a token with two curl commands, and how to keep tokens under control. The worked example is AmazHA, a Home Assistant app for Amazfit watches, because it hits every one of these points: it needs a token, it needs an administrator’s token, and it has to cope with tokens that arrive mangled by a copy and paste.

What a long-lived access token is

A long-lived access token is a credential that lets a program act as your Home Assistant user without going through the login screen. When you sign in to the web interface, Home Assistant hands your browser a short access token (30 minutes) and a refresh token that renews it. A script, a phone app or a watch app cannot easily run that login flow, so Home Assistant offers a second kind of token: one you create by hand, copy once and give to the program.

Three properties matter in practice:

• It is valid for 10 years. Home Assistant’s own authentication API documentation says long-lived tokens “are valid for 10 years”, and the profile page repeats it: each token is valid for 10 years from creation.
• It is shown once. Home Assistant does not store the token itself, so it cannot display it again. If you lose it, you make a new one.
• It is the user who made it. A token carries the permissions of the user that created it, no more and no less. A token made by an administrator is an administrator for every request it signs; a token made by a regular user is a regular user.

The token travels in an HTTP header on every request:

Authorization: Bearer <your token>

That is all a client has to do. There is no username, no password and no session: any request with a valid token in that header is accepted as that user.

Where to find it

You create long-lived access tokens in your own user profile, on the Security tab. In the Home Assistant app or in a browser:

1. Open the sidebar (the ≡ menu on a phone) and tap your name at the bottom.
2. In your profile, open the Security tab.
3. Further down that tab is the Long-lived access tokens section, with the list of tokens you already have and a Create token button.

Home Assistant’s user documentation puts it the same way: User profile › Security, the page where you also change your password, set up multi-factor authentication and manage refresh tokens.

“I can’t find it”

The most common reason is the tab. The profile opens on its general settings (language, theme and the like); the token section is on the Security tab. Many older guides say to scroll to the bottom of the profile page, which was true before the profile was split into tabs.

Two other reasons:

• You are looking for someone else’s token. Each user sees and manages only their own tokens. A token that another person in the household created does not appear in your profile, and you cannot delete it from there.
• You are signed in as a different user than you think. Check the name at the bottom of the sidebar. If an app needs an administrator’s token (more on that below), make sure that name belongs to an administrator before you create it.

Create and copy it

Creating a token takes four taps; copying it correctly is where things go wrong. The steps:

1. On the Security tab, under Long-lived access tokens, tap Create token.
2. Home Assistant asks you to give the token a name. Use the app’s name, for example AmazHA. Names must be unique among your tokens.
3. The next dialog shows the token with the warning “Copy your access token. It will not be shown again.” Copy it now, all of it.
4. Close the dialog. The token now appears in the list under its name, with the day it was created.

A token is a long string of letters, digits, - and _, in three parts separated by dots. Its length is the reason most copy problems happen: it does not fit on one line, so a careless selection takes part of it, and some apps shorten a long string on screen with an ellipsis (…) and then copy what they display.

Practical habits that avoid trouble:

• Use the copy button in the dialog, not a manual selection.
• Paste it straight into the app that needs it. A detour through a chat, an email or a notes app can add invisible characters, typographic quotes or line breaks.
• Do not add Bearer in front of it unless the app explicitly asks for the whole header. Almost every app adds that word itself.
• If you need it on another device, create a second token there instead of sending the first one around.

Why some apps need an administrator’s token

Some apps need an administrator’s token because Home Assistant reserves a few API endpoints for administrators, and a token can only do what its user can do. The clearest example is the template endpoint, POST /api/template, which renders a Jinja template on the server and returns the result.

In Home Assistant’s source code, the view that serves it, APITemplateView in homeassistant/components/api/__init__.py, has its post method decorated with @require_admin. That decorator checks the user behind the token; if the user is not an administrator it raises Unauthorized, which Home Assistant’s HTTP layer turns into 401 Unauthorized. The REST API documentation marks the endpoint “Admin” as well.

It is not the only one. The REST API splits roughly like this:

So why would an app need the template endpoint at all? Because some information is not in the plain REST endpoints. The clearest case is areas: /api/states returns every entity with its state and attributes, but not the area it belongs to, and the REST API has no endpoint that lists areas. A template can ask for them: area_id(entity_id) and area_name(...) return the area Home Assistant resolves for each entity, through the entity’s own setting or its device’s. An app that wants to show your home room by room, the way Home Assistant’s dashboards do, therefore renders a template, and needs an administrator to do it.

Is giving an app admin rights a good idea?

Home Assistant’s own security advice is to give administrator access only to accounts that need it. An app that needs /api/template is such a case, and you have two reasonable ways to handle it:

• Create the token as your own administrator user. The simplest option. The token is listed under your profile with its name, and deleting it revokes that app alone.
• Create a separate administrator user for the app in Settings › People, sign in as that user once, and create the token there. Its “last used” information stays separate from yours, and you can switch the whole user off later. Keep it active while the app uses it: a deactivated user’s tokens stop working. Do not tick Local access only if the app also connects from outside your home, for the reason in the 401 section below.

Either way, the token deserves the care you give a password: an administrator’s token can do everything you can do in Home Assistant.

“It works but shows nothing”: the 401 on /api/template

When an app connects successfully and still shows nothing, the cause is almost always a token from a user who is not an administrator. The connection test passes, because most apps test with GET /api/ and that endpoint accepts any valid token. States can be read, too. Only the template request fails, with a 401, and an app that builds its device list from that template ends up with nothing to show.

The sequence, from the app’s side:

1. GET /api/ with the token: 200, {"message": "API running."}. The app reports “connected”.
2. GET /api/states/...: 200. The states are there.
3. POST /api/template to map entities to areas: 401. No areas, so no rooms, so an empty screen.

What makes it confusing is that nothing else looks wrong. The address is right, the token is valid, Home Assistant is up. Even actions can work: POST /api/services/... is open to regular users, so a light can still be switched from the app with the same token.

What Home Assistant shows

Home Assistant counts every 401 it sends as a failed login, including the one from the admin check. Its log gets a warning that begins “Login attempt or request with invalid authentication from …”, naming the address the request came from (at home, usually your phone or your server), and the web interface shows a Login attempt failed notification. If you have turned on IP banning with a number of login attempts before a ban, enough of those 401s will ban that address: from then on it gets 403 Forbidden for everything, until you remove it from ip_bans.yaml and restart Home Assistant.

So if you see repeated “Login attempt failed” notifications pointing at your own phone, an app with a regular user’s token calling an admin-only endpoint is one explanation, besides a token that was deleted.

How AmazHA detects it and words it

AmazHA, which reads your areas through /api/template, checks for this case on purpose instead of leaving you with an empty watch:

• When you tap Connect, the phone first checks the address with GET /api/, then sends one trivial template, {{ 1 }}, to /api/template. If that template is refused with a 401, a 403 or a 400, the token is flagged as not an administrator’s. The Home Assistant screen then shows Connected ✓ with an amber line under it: “Connected, but this token has no admin permissions, so the watch can’t load your entities. Create a long-lived token from a Home Assistant user with the Administrator role and paste it above.”
• On the watch, when the rooms cannot be loaded because the area template is refused, the home shows the banner Admin token needed · “Your token lacks admin rights — use a Home Assistant admin user”, instead of a generic Offline.
• In the support report you can send from the AmazHA settings, a “HA token” row says whether the token was recognised as an administrator’s, without ever including the token.

The fix is the same in every case: create a new long-lived token while signed in as an administrator, paste it in, tap Connect again. Step 5 of When something’s wrong shows it in the video.

How to check that a user is an administrator

Open Settings › People, then the Users tab. The Group column says Administrators for an administrator; opening a user shows the Administrator switch (“Administrators can manage users, devices, automations and dashboards.”).

There is a quicker test: if the sidebar of the account you are signed in with has no Settings entry at all, that user is not an administrator. Home Assistant registers its configuration panel as admin-only, so regular users never see it. In that case, sign out, sign in as an administrator and create the token there.

Check it yourself with curl

You can test any token in a minute from a computer on the same network, with two curl commands: one against /api/, which any valid token passes, and one against /api/template, which only an administrator’s token passes. The examples use 192.168.1.50:8123 as the address of Home Assistant; replace it with yours. They run as written in a macOS or Linux terminal.

To keep the token out of your shell history, read it into a variable first. Paste the token when the command waits, then press Enter:

read -rs HA_TOKEN

Test 1: is the token valid?

curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $HA_TOKEN" \
  http://192.168.1.50:8123/api/

A valid token answers {"message":"API running."} and HTTP 200. Mind the trailing slash: the endpoint is /api/, not /api.

Test 2: is the token an administrator’s?

curl -s -w "\nHTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{{ 1 }}"}' \
  http://192.168.1.50:8123/api/template

An administrator’s token gets the rendered template, 1, and HTTP 200. A regular user’s token gets HTTP 401.

How to read the two results together:

Two caveats. First, this tests the token from your computer; an app on your phone may take a different route to Home Assistant, especially away from home. Second, a passing test 1 alone proves very little for apps that need areas: it is exactly the test a regular user’s token passes.

The “Local access only” 401

A user with Local access only turned on can sign in only from your local network, and Home Assistant applies the same rule to that user’s tokens. A request from an address outside your network, or one that arrives through Home Assistant Cloud, is refused with a 401, even though the same token works perfectly at home. If an app works on your Wi-Fi and fails with a 401 away from home, open the user in Settings › People and look at that switch before you suspect the remote address. For the remote address itself, see Home Assistant away from home on your watch.

Paste problems

A token that looks right can still be wrong, because what you pasted is not always what Home Assistant gave you. Home Assistant compares the token character for character, so a single extra or missing character is an invalid token and a 401. The usual culprits:

The cure is the same for all of them: copy the token again with the dialog’s copy button and paste it directly. If the dialog is already closed, the token is gone; create a new one and delete the old entry.

What AmazHA cleans, and what it refuses

AmazHA handles the fixable cases itself, both when you save the token and again when the phone reads it to make a request:

• Removed: spaces, line breaks, zero-width characters, no-break spaces, byte-order marks, soft hyphens and direction marks, anywhere in the token. None of them can be part of a Home Assistant token, which is made of letters, digits, -, _ and dots.
• Stripped from the ends: straight and typographic quotes, backticks and guillemets.
• Dropped from the start: a pasted Bearer (in any capitalisation), because AmazHA adds that word itself.

What cleaning cannot fix is a visible character that no token contains, typically the … of a copy that was cut short. AmazHA does not guess: it refuses to send that token at all, so no request reaches Home Assistant and no failed login is counted. The Home Assistant screen in the settings shows Token not valid, with the explanation “The token contains a character a Home Assistant token can’t have — usually a copy that was cut short (…). Copy the whole token again from your Home Assistant profile › Security and paste it above.” The watch shows Check the token · “It has a character no HA token has — paste it again”. That is step 6 of When something’s wrong.

Keep it safe

Treat every long-lived token like a password that does not expire for 10 years: one token per app, a name that says which app, and delete it the day you stop using that app. Concretely:

• One token per app or device. If you give the same token to three programs, you cannot revoke one without breaking the other two, and you cannot tell which of them is calling.
• Name it after the app. “AmazHA”, “Backup script”, “Wall tablet”. The name is all you see in the list later; the token itself is never shown again.
• Look at the list now and then. Each entry shows when it was created and, once used, when and from where it was last used. A token nobody has used for months is a candidate for deletion.
• Revoke by deleting. On the Security tab, delete the token by its name. The app that used it fails at its next request, with a 401; nothing else is touched.
• If a token may have leaked, delete it and create a new one. Deleting is the one way to revoke a single token; the replacement goes into the app in a minute.
• Never paste a token into a support request, a forum post or a screenshot. A good app’s diagnostics never need it.

Deleting all refresh tokens from the same tab signs out your devices but leaves the current session and your long-lived tokens in place, as Home Assistant’s confirmation dialog says. Long-lived tokens are revoked one by one.

In AmazHA

AmazHA needs exactly one long-lived token, from an administrator, entered once in the AmazHA settings inside the Zepp app; that one token serves both the local and the remote address, and it stays on your phone. The connection fields are available once the full version is unlocked (a one-time unlock, no subscription: see Unlock the full version). Then:

1. Create the token as an administrator, as above (steps 1–3 of Connect Home Assistant).
2. In the Zepp app, go to Profile › your watch › Apps › AmazHA › Settings, then tap Home Assistant (step 4).
3. Enter your address at home in Local URL (LAN), for example http://192.168.1.50:8123, and, if you want the watch to work away from home too, the outside address in Remote URL. Either field can stay empty.
4. Paste the token into Long-lived access token (step 7).
5. Tap Connect. With both addresses set, the result shows each one, LAN and Remote; with one address it reads Connected ✓. If the token is not an administrator’s, the amber line described above appears under it.

One token, two addresses

You do not need a second token for the remote address. A token belongs to a user, not to an address: the same token is valid whether the request reaches Home Assistant over your Wi-Fi or from outside. At home AmazHA uses the local address; the remote one is only for when the phone is away. The one exception is the Local access only user described above, whose token is refused from outside by design.

Where the token goes, and where it does not

The watch never talks to Home Assistant directly. Your phone does, through the Zepp app, and the token is stored there, on the phone. It is sent only to your Home Assistant server, in the Authorization header of the phone’s own requests; it is never sent to the watch, which receives only what it shows over its Bluetooth link with the phone. AmazHA has no server of its own for the token to pass through, and the support report never includes it.

What the phone does with the token, request by request:

The last row is the watch-sensor feature, which sends your Amazfit’s heart rate, steps, battery and more into Home Assistant as a device of the Mobile App integration: Send your Amazfit’s data to Home Assistant covers it.

When AmazHA says something about the token

The small code under Offline is there for support: if you write in, a photo of the watch tells exactly what failed. For every other message the watch can show, see When something’s wrong.