Token de llarga durada de Home Assistant: crear-lo, per què d’administrador i «funciona però no mostra res»

La resposta curta

Un token d’accés de llarga durada és un substitut de la contrasenya per a apps i scripts: el crees al teu perfil de Home Assistant, a la pestanya Seguretat, a ‘Tokens’ d’accés de llarga durada, i Home Assistant només te’l mostra un cop. És vàlid durant 10 anys. Algunes apps necessiten un token d’un administrador, perquè hi ha parts de l’API, com /api/template, que rebutgen qualsevol altre usuari amb un 401.

La resta de l’article repassa cada peça: què és el token, on trobar-lo, com copiar-lo sense espatllar-lo, per què importa la qüestió de l’administrador, com provar un token amb dues ordres curl i com mantenir els tokens sota control. L’exemple pràctic és AmazHA, una app de Home Assistant per a rellotges Amazfit, perquè toca tots aquests punts: necessita un token, necessita el token d’un administrador i ha de saber gestionar tokens que arriben malmesos per un copia i enganxa.

Què és un token d’accés de llarga durada

Un token d’accés de llarga durada és una credencial que permet a un programa actuar com el teu usuari de Home Assistant sense passar per la pantalla d’inici de sessió. Quan inicies sessió a la interfície web, Home Assistant dona al navegador un token d’accés curt (30 minuts) i un token de refresc que el renova. Un script, una app de mòbil o una app de rellotge no poden fer fàcilment aquest procés d’inici de sessió, així que Home Assistant ofereix un segon tipus de token: un que crees a mà, copies un cop i dones al programa.

A la pràctica, hi ha tres propietats que importen:

• És vàlid durant 10 anys. La mateixa documentació de l’API d’autenticació de Home Assistant diu que els tokens de llarga durada «són vàlids durant 10 anys», i la pàgina del perfil ho repeteix: cada token és vàlid durant 10 anys des que es crea.
• Es mostra un sol cop. Home Assistant no guarda el token en si, així que no el pot tornar a mostrar. Si el perds, en fas un de nou.
• És l’usuari que l’ha creat. Un token porta els permisos de l’usuari que l’ha creat, ni més ni menys. Un token creat per un administrador és un administrador per a cada petició que signa; un token creat per un usuari normal és un usuari normal.

El token viatja en una capçalera HTTP a cada petició:

Authorization: Bearer <your token>

Això és tot el que ha de fer un client. No hi ha nom d’usuari, ni contrasenya, ni sessió: qualsevol petició amb un token vàlid en aquesta capçalera s’accepta com a aquest usuari.

On trobar-lo

Els tokens d’accés de llarga durada es creen al teu propi perfil d’usuari, a la pestanya Seguretat. A l’app de Home Assistant o en un navegador:

1. Obre la barra lateral (el menú ≡ en un mòbil) i toca el teu nom, a baix de tot.
2. Al teu perfil, obre la pestanya Seguretat.
3. Més avall, en aquesta pestanya, hi ha la secció ‘Tokens’ d’accés de llarga durada, amb la llista dels tokens que ja tens i un botó Crea ‘token’.

La documentació d’usuari de Home Assistant ho explica igual: User profile › Security, la pàgina on també canvies la contrasenya, configures l’autenticació multifactor i gestiones els tokens de refresc.

«No el trobo»

El motiu més habitual és la pestanya. El perfil s’obre a la configuració general (idioma, tema i similars); la secció de tokens és a la pestanya Seguretat. Moltes guies antigues diuen que baixis fins al final de la pàgina del perfil, cosa que era certa abans que el perfil es dividís en pestanyes.

Dos motius més:

• Busques el token d’una altra persona. Cada usuari només veu i gestiona els seus propis tokens. Un token que ha creat una altra persona de casa no apareix al teu perfil, i no el pots esborrar des d’allà.
• Has iniciat sessió amb un usuari diferent del que creus. Comprova el nom a baix de tot de la barra lateral. Si una app necessita un token d’administrador (en parlem més avall), assegura’t que aquest nom és d’un administrador abans de crear-lo.

Crea’l i copia’l

Crear un token són quatre tocs; copiar-lo bé és on les coses es torcen. Els passos:

1. A la pestanya Seguretat, a ‘Tokens’ d’accés de llarga durada, toca Crea ‘token’.
2. Home Assistant et demana que li posis un nom. Fes servir el nom de l’app, per exemple AmazHA. Els noms han de ser únics entre els teus tokens.
3. El diàleg següent mostra el token amb l’avís que el copiïs ara, perquè no es tornarà a mostrar. Copia’l en aquest moment, sencer.
4. Tanca el diàleg. El token apareix a la llista amb el seu nom i el dia en què es va crear.

Un token és una cadena llarga de lletres, xifres, - i _, en tres parts separades per punts. La seva llargada és el motiu de la majoria de problemes en copiar-lo: no cap en una línia, així que una selecció descuidada n’agafa només una part, i algunes apps escurcen una cadena llarga a la pantalla amb punts suspensius (…) i després copien el que mostren.

Hàbits pràctics que estalvien problemes:

• Fes servir el botó de copiar del diàleg, no una selecció manual.
• Enganxa’l directament a l’app que el necessita. Si passa per un xat, un correu o una app de notes, s’hi poden afegir caràcters invisibles, cometes tipogràfiques o salts de línia.
• No hi afegeixis Bearer al davant tret que l’app demani explícitament tota la capçalera. Gairebé totes les apps ja hi afegeixen aquesta paraula.
• Si el necessites en un altre dispositiu, crea-hi un segon token en lloc d’anar passant el primer.

Per què algunes apps necessiten el token d’un administrador

Algunes apps necessiten el token d’un administrador perquè Home Assistant reserva uns quants punts d’accés de l’API als administradors, i un token només pot fer el que pot fer el seu usuari. L’exemple més clar és el punt d’accés de plantilles, POST /api/template, que renderitza una plantilla Jinja al servidor i en retorna el resultat.

Al codi font de Home Assistant, la vista que el serveix, APITemplateView a homeassistant/components/api/__init__.py, té el mètode post decorat amb @require_admin. Aquest decorador comprova l’usuari que hi ha darrere del token; si l’usuari no és administrador, llança Unauthorized, que la capa HTTP de Home Assistant converteix en 401 Unauthorized. La documentació de l’API REST també marca aquest punt d’accés com a «Admin».

No és l’únic. L’API REST es reparteix més o menys així:

Llavors, per què necessitaria una app el punt d’accés de plantilles? Perquè hi ha informació que no surt als punts d’accés REST bàsics. El cas més clar són les àrees: /api/states retorna totes les entitats amb el seu estat i els seus atributs, però no l’àrea a la qual pertanyen, i l’API REST no té cap punt d’accés que llisti les àrees. Una plantilla les pot demanar: area_id(entity_id) i area_name(...) retornen l’àrea que Home Assistant resol per a cada entitat, a través de la configuració de la mateixa entitat o de la del seu dispositiu. Una app que vol mostrar la teva llar habitació per habitació, com fan els taulers de Home Assistant, per tant renderitza una plantilla, i li cal un administrador per fer-ho.

És bona idea donar permisos d’administrador a una app?

El consell de seguretat de Home Assistant és donar accés d’administrador només als comptes que el necessiten. Una app que necessita /api/template n’és un cas, i tens dues maneres raonables de gestionar-ho:

• Crea el token amb el teu propi usuari administrador. És l’opció més senzilla. El token surt al teu perfil amb el seu nom, i esborrar-lo revoca només aquella app.
• Crea un usuari administrador separat per a l’app a Configuració › Persones, inicia sessió amb aquest usuari un cop i crea-hi el token. La seva informació de «darrer ús» queda separada de la teva, i més endavant pots desactivar tot l’usuari. Mantén-lo actiu mentre l’app el faci servir: els tokens d’un usuari desactivat deixen de funcionar. No marquis Local access only (només accés local) si l’app també es connecta des de fora de casa, pel motiu que s’explica a la secció del 401, més avall.

En qualsevol cas, el token mereix la cura que dones a una contrasenya: el token d’un administrador pot fer tot el que tu pots fer a Home Assistant.

«Funciona però no mostra res»: el 401 a /api/template

Quan una app es connecta correctament i tot i així no mostra res, la causa és gairebé sempre un token d’un usuari que no és administrador. La prova de connexió passa, perquè la majoria d’apps proven amb GET /api/ i aquest punt d’accés accepta qualsevol token vàlid. També es poden llegir els estats. Només falla la petició de plantilla, amb un 401, i una app que construeix la seva llista de dispositius a partir d’aquella plantilla es queda sense res per mostrar.

La seqüència, des del costat de l’app:

1. GET /api/ amb el token: 200, {"message": "API running."}. L’app informa que està «connectada».
2. GET /api/states/...: 200. Els estats hi són.
3. POST /api/template per assignar entitats a àrees: 401. Sense àrees, no hi ha habitacions, i per tant la pantalla queda buida.

El que ho fa confús és que no sembla que hi hagi res més malament. L’adreça és correcta, el token és vàlid, Home Assistant funciona. Fins i tot les accions poden funcionar: POST /api/services/... està obert als usuaris normals, així que es pot continuar encenent un llum des de l’app amb el mateix token.

Què mostra Home Assistant

Home Assistant compta cada 401 que envia com un inici de sessió fallit, inclòs el de la comprovació d’administrador. Al registre hi apareix un avís que comença amb “Login attempt or request with invalid authentication from …”, amb l’adreça d’on venia la petició (a casa, normalment el teu mòbil o el teu servidor), i la interfície web mostra una notificació Login attempt failed (intent d’inici de sessió fallit). Si has activat el bloqueig d’IP amb un nombre d’intents d’inici de sessió abans de bloquejar, prou d’aquests 401 bloquejaran aquella adreça: a partir d’aleshores rep 403 Forbidden per a tot, fins que la treguis d’ip_bans.yaml i reiniciïs Home Assistant.

Així doncs, si veus notificacions repetides d’inici de sessió fallit que apunten al teu propi mòbil, una possible explicació és una app amb el token d’un usuari normal que crida un punt d’accés reservat als administradors, a més d’un token que s’ha esborrat.

Com ho detecta i ho explica AmazHA

AmazHA, que llegeix les teves àrees a través de /api/template, comprova aquest cas expressament en lloc de deixar-te amb un rellotge buit:

• Quan toques Connecta, el mòbil comprova primer l’adreça amb GET /api/ i després envia una plantilla trivial, {{ 1 }}, a /api/template. Si aquesta plantilla es rebutja amb un 401, un 403 o un 400, el token es marca com a no d’administrador. Llavors la pantalla Home Assistant mostra Connectat ✓ amb una línia ambre a sota: «Connectat, però aquest token no té permisos d’administrador, així que el rellotge no pot carregar les teves entitats. Crea un token de llarga durada des d’un usuari de Home Assistant amb el rol Administrator i enganxa’l a dalt.»
• Al rellotge, quan no es poden carregar les habitacions perquè es rebutja la plantilla d’àrees, la pantalla d’inici mostra el bàner Cal un token admin · «El token no té permisos d’administrador — fes servir un usuari admin de Home Assistant», en lloc d’un genèric Sense connexió.
• A l’informe de suport que pots enviar des de la configuració d’AmazHA, una fila «HA token» indica si el token s’ha reconegut com d’administrador, sense incloure mai el token.

La solució és la mateixa en tots els casos: crea un token de llarga durada nou amb la sessió iniciada com a administrador, enganxa’l i torna a tocar Connecta. El pas 5 de Quan alguna cosa falla ho mostra en vídeo.

Com comprovar que un usuari és administrador

Obre Configuració › Persones i després la pestanya Usuaris. La columna Grup diu Administradors per a un administrador; si obres un usuari, veuràs l’interruptor Administrador, la descripció del qual explica que els administradors poden gestionar usuaris, dispositius, automatitzacions i taulers.

Hi ha una prova més ràpida: si la barra lateral del compte amb què has iniciat sessió no té cap entrada Configuració, aquest usuari no és administrador. Home Assistant registra el seu tauler de configuració com a reservat als administradors, així que els usuaris normals no el veuen mai. En aquest cas, tanca la sessió, inicia-la com a administrador i crea-hi el token.

Comprova-ho tu mateix amb curl

Pots provar qualsevol token en un minut des d’un ordinador de la mateixa xarxa, amb dues ordres curl: una contra /api/, que passa amb qualsevol token vàlid, i una contra /api/template, que només passa amb el token d’un administrador. Els exemples fan servir 192.168.1.50:8123 com a adreça de Home Assistant; canvia-la per la teva. Funcionen tal com estan en un terminal de macOS o Linux.

Per evitar que el token quedi a l’historial de l’intèrpret d’ordres, llegeix-lo primer en una variable. Enganxa el token quan l’ordre s’esperi i després prem Retorn:

read -rs HA_TOKEN

Prova 1: el token és vàlid?

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

Un token vàlid respon {"message":"API running."} i HTTP 200. Compte amb la barra final: el punt d’accés és /api/, no /api.

Prova 2: el token és d’un administrador?

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

El token d’un administrador rep la plantilla renderitzada, 1, i HTTP 200. El token d’un usuari normal rep HTTP 401.

Com llegir els dos resultats junts:

Dues advertències. Primer, això prova el token des del teu ordinador; una app del mòbil pot fer un camí diferent per arribar a Home Assistant, sobretot fora de casa. Segon, que la prova 1 passi per si sola demostra molt poc per a les apps que necessiten àrees: és exactament la prova que passa el token d’un usuari normal.

El 401 de «Local access only»

Un usuari amb Local access only (només accés local) activat només pot iniciar sessió des de la teva xarxa local, i Home Assistant aplica la mateixa regla als tokens d’aquest usuari. Una petició des d’una adreça de fora de la xarxa, o una que arriba a través de Home Assistant Cloud, es rebutja amb un 401, encara que el mateix token funcioni perfectament a casa. Si una app funciona amb la teva wifi i falla amb un 401 fora de casa, obre l’usuari a Configuració › Persones i mira aquest interruptor abans de sospitar de l’adreça remota. Per a l’adreça remota en si, mira Home Assistant fora de casa al teu rellotge.

Problemes en enganxar-lo

Un token que sembla correcte pot ser incorrecte igualment, perquè el que has enganxat no sempre és el que t’ha donat Home Assistant. Home Assistant compara el token caràcter per caràcter, així que un sol caràcter de més o de menys fa que el token no sigui vàlid i doni un 401. Els culpables habituals:

El remei és el mateix per a tots: torna a copiar el token amb el botó de copiar del diàleg i enganxa’l directament. Si el diàleg ja està tancat, el token s’ha perdut; crea’n un de nou i esborra l’entrada antiga.

Què neteja AmazHA i què rebutja

AmazHA gestiona tot sol els casos que tenen solució, tant quan deses el token com quan el mòbil el torna a llegir per fer una petició:

• S’eliminen: espais, salts de línia, caràcters d’amplada zero, espais no separables, marques d’ordre de bytes, guionets discrecionals i marques de direcció, a qualsevol punt del token. Cap d’aquests caràcters pot formar part d’un token de Home Assistant, que està fet de lletres, xifres, -, _ i punts.
• Es treuen dels extrems: cometes rectes i tipogràfiques, accents greus i cometes angulars.
• Es treu del començament: un Bearer enganxat (amb qualsevol combinació de majúscules), perquè AmazHA ja hi afegeix aquesta paraula.

El que la neteja no pot arreglar és un caràcter visible que cap token no conté, normalment els … d’una còpia tallada. AmazHA no endevina: es nega a enviar aquest token, així que cap petició arriba a Home Assistant i no es compta cap inici de sessió fallit. La pantalla Home Assistant de la configuració mostra Token no vàlid, amb l’explicació «El token conté un caràcter que un token de Home Assistant no pot tenir — sol ser una còpia tallada (…). Torna a copiar el token sencer des del teu perfil de Home Assistant › Seguretat i enganxa’l a dalt.» El rellotge mostra Revisa el token · «Té un caràcter no vàlid — torna’l a enganxar». És el pas 6 de Quan alguna cosa falla.

Mantén-lo segur

Tracta cada token de llarga durada com una contrasenya que no caduca en 10 anys: un token per app, un nom que digui de quina app és, i esborra’l el dia que deixis de fer servir aquella app. En concret:

• Un token per app o dispositiu. Si dones el mateix token a tres programes, no en pots revocar un sense trencar els altres dos, i no pots saber quin d’ells fa les crides.
• Posa-li el nom de l’app. «AmazHA», «Script de còpia de seguretat», «Tauleta de la paret». El nom és l’únic que veuràs després a la llista; el token en si no es torna a mostrar mai.
• Revisa la llista de tant en tant. Cada entrada mostra quan es va crear i, un cop s’ha fet servir, quan i des d’on es va fer servir per última vegada. Un token que ningú no ha fet servir en mesos és candidat a ser esborrat.
• Revoca’l esborrant-lo. A la pestanya Seguretat, esborra el token pel seu nom. L’app que el feia servir falla a la seva propera petició, amb un 401; no es toca res més.
• Si un token pot haver-se filtrat, esborra’l i crea’n un de nou. Esborrar-lo és l’única manera de revocar un sol token; el substitut s’introdueix a l’app en un minut.
• No enganxis mai un token en una petició de suport, una publicació en un fòrum o una captura de pantalla. Les diagnosis d’una bona app no el necessiten mai.

Esborrar tots els tokens de refresc des de la mateixa pestanya tanca la sessió dels teus dispositius, però manté la sessió actual i els teus tokens de llarga durada, tal com diu el diàleg de confirmació de Home Assistant. Els tokens de llarga durada es revoquen un per un.

A AmazHA

AmazHA necessita exactament un token de llarga durada, d’un administrador, introduït un sol cop a la configuració d’AmazHA dins de l’app Zepp; aquest únic token serveix tant per a l’adreça local com per a la remota, i es queda al mòbil. Els camps de connexió estan disponibles un cop desbloquejada la versió completa (un desbloqueig únic, sense subscripció: mira Desbloqueja la versió completa). Després:

1. Crea el token com a administrador, com s’ha explicat més amunt (passos 1–3 de Connecta Home Assistant).
2. A l’app Zepp, ves a Perfil › el teu rellotge › Aplicacions › AmazHA › Configuració i toca Home Assistant (pas 4).
3. Introdueix la teva adreça de casa a URL local (LAN), per exemple http://192.168.1.50:8123, i, si vols que el rellotge també funcioni fora de casa, l’adreça exterior a URL remot. Qualsevol dels dos camps pot quedar buit.
4. Enganxa el token a Token d’accés de llarga durada (pas 7).
5. Toca Connecta. Amb les dues adreces configurades, el resultat mostra cadascuna, LAN i Remot; amb una sola adreça diu Connectat ✓. Si el token no és d’un administrador, hi apareix a sota la línia ambre descrita més amunt.

Un token, dues adreces

No necessites un segon token per a l’adreça remota. Un token pertany a un usuari, no a una adreça: el mateix token és vàlid tant si la petició arriba a Home Assistant per la teva wifi com des de fora. A casa, AmazHA fa servir l’adreça local; la remota només és per quan el mòbil és fora. L’única excepció és l’usuari amb Local access only descrit més amunt, el token del qual es rebutja des de fora per disseny.

On va el token, i on no

El rellotge no parla mai directament amb Home Assistant. Ho fa el mòbil, a través de l’app Zepp, i el token es guarda allà, al mòbil. Només s’envia al teu servidor de Home Assistant, a la capçalera Authorization de les peticions del mateix mòbil; no s’envia mai al rellotge, que només rep el que mostra pel seu enllaç Bluetooth amb el mòbil. AmazHA no té cap servidor propi per on hagi de passar el token, i l’informe de suport no l’inclou mai.

Què fa el mòbil amb el token, petició per petició:

L’última fila és la funció de sensors del rellotge, que envia a Home Assistant la freqüència cardíaca, els passos, la bateria i més del teu Amazfit com un dispositiu de la integració Mobile App: Envia les dades del teu Amazfit a Home Assistant ho explica.

Quan AmazHA diu alguna cosa sobre el token

El petit codi sota Sense connexió és per al suport: si ens escrius, una foto del rellotge indica exactament què ha fallat. Per a qualsevol altre missatge que pugui mostrar el rellotge, mira Quan alguna cosa falla.