Token de larga duración de Home Assistant: crearlo, por qué de administrador y «funciona, pero no se ve nada»

La respuesta corta

Un token de acceso de larga duración sustituye a la contraseña para apps y scripts: lo creas en tu perfil de Home Assistant, en la pestaña Seguridad, en Tokens de acceso de larga duración, y Home Assistant solo lo muestra una vez. Es válido durante 10 años. Algunas apps necesitan el token de un administrador, porque partes de la API, como /api/template, rechazan a cualquier otro usuario con un 401.

El resto del artículo repasa cada pieza: qué es el token, dónde encontrarlo, cómo copiarlo sin romperlo, por qué importa la cuestión del administrador, cómo probar un token con dos comandos curl y cómo mantener los tokens bajo control. El ejemplo práctico es AmazHA, una app de Home Assistant para relojes Amazfit, porque pasa por todos estos puntos: necesita un token, necesita el token de un administrador y tiene que lidiar con tokens que llegan estropeados por un copiar y pegar.

Qué es un token de acceso de larga duración

Un token de acceso de larga duración es una credencial que permite a un programa actuar como tu usuario de Home Assistant sin pasar por la pantalla de inicio de sesión. Cuando inicias sesión en la interfaz web, Home Assistant le da a tu navegador un token de acceso corto (30 minutos) y un token de actualización que lo renueva. Un script, una app de móvil o una app de reloj no pueden seguir fácilmente ese proceso de inicio de sesión, así que Home Assistant ofrece un segundo tipo de token: uno que creas a mano, copias una vez y le das al programa.

En la práctica importan tres propiedades:

• Es válido durante 10 años. La propia documentación de la API de autenticación de Home Assistant dice que los tokens de larga duración son válidos durante 10 años, y la página del perfil lo repite: cada token es válido durante 10 años desde su creación.
• Se muestra una sola vez. Home Assistant no guarda el token en sí, así que no puede volver a mostrarlo. Si lo pierdes, creas uno nuevo.
• Es el usuario que lo creó. Un token lleva los permisos del usuario que lo creó, ni más ni menos. Un token creado por un administrador es un administrador en cada petición que firma; un token creado por un usuario normal es un usuario normal.

El token viaja en una cabecera HTTP en cada petición:

Authorization: Bearer <your token>

Es todo lo que tiene que hacer un cliente. No hay nombre de usuario, ni contraseña, ni sesión: cualquier petición con un token válido en esa cabecera se acepta como ese usuario.

Dónde encontrarlo

Los tokens de acceso de larga duración se crean en tu propio perfil de usuario, en la pestaña Seguridad. En la app de Home Assistant o en un navegador:

1. Abre la barra lateral (el menú ≡ en un móvil) y toca tu nombre, abajo del todo.
2. En tu perfil, abre la pestaña Seguridad.
3. Más abajo en esa pestaña está la sección Tokens de acceso de larga duración, con la lista de los tokens que ya tienes y un botón Crear token.

La documentación de usuario de Home Assistant lo explica igual: Perfil de usuario › Seguridad, la página donde también cambias tu contraseña, configuras la autenticación de varios factores y gestionas los tokens de actualización.

«No lo encuentro»

El motivo más habitual es la pestaña. El perfil se abre en sus ajustes generales (idioma, tema y similares); la sección de tokens está en la pestaña Seguridad. Muchas guías antiguas dicen que te desplaces hasta el final de la página del perfil, lo que era cierto antes de que el perfil se dividiera en pestañas.

Otros dos motivos:

• Buscas el token de otra persona. Cada usuario solo ve y gestiona sus propios tokens. Un token que creó otra persona de la casa no aparece en tu perfil, y no puedes eliminarlo desde ahí.
• Has iniciado sesión con un usuario distinto del que crees. Comprueba el nombre que aparece abajo en la barra lateral. Si una app necesita el token de un administrador (más sobre esto abajo), asegúrate de que ese nombre es de un administrador antes de crearlo.

Créalo y cópialo

Crear un token lleva cuatro toques; copiarlo bien es donde las cosas se tuercen. Los pasos:

1. En la pestaña Seguridad, en Tokens de acceso de larga duración, toca Crear token.
2. Home Assistant te pide un nombre para el token. Usa el nombre de la app, por ejemplo AmazHA. Los nombres tienen que ser únicos entre tus tokens.
3. El siguiente cuadro de diálogo muestra el token con el aviso de que lo copies porque no se volverá a mostrar. Cópialo ahora, entero.
4. Cierra el cuadro de diálogo. El token aparece ahora en la lista con su nombre y el día en que se creó.

Un token es una cadena larga de letras, cifras, - y _, en tres partes separadas por puntos. Su longitud es la causa de la mayoría de los problemas al copiar: no cabe en una línea, así que una selección descuidada se queda con una parte, y algunas apps acortan en pantalla una cadena larga con puntos suspensivos (…) y luego copian lo que muestran.

Hábitos prácticos que evitan problemas:

• Usa el botón de copiar del cuadro de diálogo, no una selección manual.
• Pégalo directamente en la app que lo necesita. Un rodeo por un chat, un correo o una app de notas puede añadir caracteres invisibles, comillas tipográficas o saltos de línea.
• No añadas Bearer delante a menos que la app pida expresamente la cabecera completa. Casi todas las apps añaden esa palabra por su cuenta.
• Si lo necesitas en otro dispositivo, crea allí un segundo token en lugar de ir pasando el primero.

Por qué algunas apps necesitan el token de un administrador

Algunas apps necesitan el token de un administrador porque Home Assistant reserva unos pocos endpoints de la API a los administradores, y un token solo puede hacer lo que puede hacer su usuario. El ejemplo más claro es el endpoint de plantillas, POST /api/template, que procesa una plantilla Jinja en el servidor y devuelve el resultado.

En el código fuente de Home Assistant, la vista que lo sirve, APITemplateView en homeassistant/components/api/__init__.py, tiene su método post decorado con @require_admin. Ese decorador comprueba el usuario que hay detrás del token; si no es administrador, lanza Unauthorized, que la capa HTTP de Home Assistant convierte en 401 Unauthorized. La documentación de la API REST también marca el endpoint como «Admin».

No es el único. La API REST se reparte más o menos así:

Entonces, ¿para qué necesitaría una app el endpoint de plantillas? Porque parte de la información no está en los endpoints REST simples. El caso más claro son las áreas: /api/states devuelve cada entidad con su estado y sus atributos, pero no el área a la que pertenece, y la API REST no tiene ningún endpoint que liste las áreas. Una plantilla sí puede preguntarlo: area_id(entity_id) y area_name(...) devuelven el área que Home Assistant resuelve para cada entidad, a partir del ajuste de la propia entidad o del de su dispositivo. Una app que quiere mostrar tu casa habitación por habitación, como hacen los paneles de Home Assistant, procesa por tanto una plantilla, y necesita un administrador para hacerlo.

¿Es buena idea dar permisos de administrador a una app?

El propio consejo de seguridad de Home Assistant es dar acceso de administrador solo a las cuentas que lo necesitan. Una app que necesita /api/template es uno de esos casos, y tienes dos formas razonables de gestionarlo:

• Crea el token con tu propio usuario administrador. La opción más sencilla. El token aparece en tu perfil con su nombre, y eliminarlo revoca solo esa app.
• Crea un usuario administrador aparte para la app en Configuración › Personas, inicia sesión con ese usuario una vez y crea allí el token. Su información de «último uso» queda separada de la tuya, y más adelante puedes desactivar todo el usuario. Mantenlo activo mientras la app lo use: los tokens de un usuario desactivado dejan de funcionar. No marques Local access only si la app también se conecta desde fuera de casa, por el motivo que se explica en la sección del 401 más abajo.

En cualquier caso, el token merece el mismo cuidado que una contraseña: un token de administrador puede hacer todo lo que tú puedes hacer en Home Assistant.

«Funciona, pero no muestra nada»: el 401 en /api/template

Cuando una app se conecta bien y aun así no muestra nada, la causa es casi siempre un token de un usuario que no es administrador. La prueba de conexión sale bien, porque la mayoría de las apps prueban con GET /api/ y ese endpoint acepta cualquier token válido. También se pueden leer los estados. Solo falla la petición de plantilla, con un 401, y una app que construye su lista de dispositivos a partir de esa plantilla se queda sin nada que mostrar.

La secuencia, vista desde la app:

1. GET /api/ con el token: 200, {"message": "API running."}. La app indica «conectado».
2. GET /api/states/...: 200. Los estados están ahí.
3. POST /api/template para asignar entidades a áreas: 401. Sin áreas no hay habitaciones, y sin habitaciones la pantalla queda vacía.

Lo que lo hace confuso es que nada más parece estar mal. La dirección es correcta, el token es válido, Home Assistant funciona. Incluso las acciones pueden funcionar: POST /api/services/... está abierto a los usuarios normales, así que con el mismo token se puede seguir encendiendo una luz desde la app.

Lo que muestra Home Assistant

Home Assistant cuenta cada 401 que envía como un inicio de sesión fallido, incluido el de la comprobación de administrador. Su registro recibe un aviso que empieza por «Login attempt or request with invalid authentication from …», con la dirección de la que llegó la petición (en casa, normalmente tu móvil o tu servidor), y la interfaz web muestra una notificación Login attempt failed (intento de inicio de sesión fallido). Si has activado el bloqueo de IP con un número de intentos de inicio de sesión antes del bloqueo, suficientes 401 de ese tipo bloquearán esa dirección: a partir de ahí recibe 403 Forbidden para todo, hasta que la quites de ip_bans.yaml y reinicies Home Assistant.

Así que, si ves notificaciones repetidas de inicio de sesión fallido que apuntan a tu propio móvil, una explicación es una app con el token de un usuario normal llamando a un endpoint reservado a administradores, además de un token que se ha eliminado.

Cómo lo detecta y lo explica AmazHA

AmazHA, que lee tus áreas a través de /api/template, comprueba este caso a propósito en lugar de dejarte con el reloj vacío:

• Cuando tocas Conectar, el móvil comprueba primero la dirección con GET /api/ y después envía una plantilla trivial, {{ 1 }}, a /api/template. Si esa plantilla se rechaza con un 401, un 403 o un 400, el token se marca como no perteneciente a un administrador. La pantalla Home Assistant muestra entonces Conectado ✓ con una línea ámbar debajo: «Conectado, pero este token no tiene permisos de administrador, así que el reloj no puede cargar tus entidades. Crea un token de larga duración desde un usuario de Home Assistant con el rol Administrator y pégalo arriba.»
• En el reloj, cuando las habitaciones no se pueden cargar porque se rechaza la plantilla de áreas, el inicio muestra el banner Se necesita token admin · «Tu token no tiene permisos de administrador — usa un usuario admin de Home Assistant», en lugar de un Sin conexión genérico.
• En el informe de soporte que puedes enviar desde los ajustes de AmazHA, una fila «HA token» indica si el token se reconoció como de administrador, sin incluir nunca el token.

La solución es la misma en todos los casos: crea un nuevo token de larga duración con la sesión iniciada como administrador, pégalo y vuelve a tocar Conectar. El paso 5 de Cuando algo falla lo muestra en el vídeo.

Cómo comprobar que un usuario es administrador

Abre Configuración › Personas y luego la pestaña Usuarios. La columna Grupo dice Administradores para un administrador; al abrir un usuario aparece el interruptor Administrador («Los administradores pueden gestionar usuarios, dispositivos, automatizaciones y paneles.»).

Hay una prueba más rápida: si en la barra lateral de la cuenta con la que has iniciado sesión no aparece la entrada Configuración, ese usuario no es administrador. Home Assistant registra su panel de configuración como reservado a administradores, así que los usuarios normales nunca lo ven. En ese caso, cierra sesión, iníciala como administrador y crea el token allí.

Compruébalo tú mismo con curl

Puedes probar cualquier token en un minuto desde un ordenador de la misma red, con dos comandos curl: uno contra /api/, que supera cualquier token válido, y otro contra /api/template, que solo supera el token de un administrador. Los ejemplos usan 192.168.1.50:8123 como dirección de Home Assistant; sustitúyela por la tuya. Funcionan tal cual en un terminal de macOS o Linux.

Para que el token no quede en el historial de la terminal, léelo primero en una variable. Pega el token cuando el comando espere y pulsa Intro:

read -rs HA_TOKEN

Prueba 1: ¿el token es válido?

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

Un token válido responde {"message":"API running."} y HTTP 200. Ojo con la barra final: el endpoint es /api/, no /api.

Prueba 2: ¿el token es de 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 de un administrador recibe la plantilla procesada, 1, y HTTP 200. El token de un usuario normal recibe HTTP 401.

Cómo leer juntos los dos resultados:

Dos salvedades. Primera: esto prueba el token desde tu ordenador; una app del móvil puede tomar otro camino hasta Home Assistant, sobre todo fuera de casa. Segunda: superar solo la prueba 1 demuestra muy poco para las apps que necesitan áreas: es justo la prueba que supera el token de un usuario normal.

El 401 de «Local access only»

Un usuario con Local access only (solo acceso local) activado solo puede iniciar sesión desde tu red local, y Home Assistant aplica la misma regla a los tokens de ese usuario. Una petición desde una dirección de fuera de tu red, o una que llega a través de Home Assistant Cloud, se rechaza con un 401, aunque el mismo token funcione perfectamente en casa. Si una app funciona con tu wifi y falla con un 401 fuera de casa, abre el usuario en Configuración › Personas y mira ese interruptor antes de sospechar de la dirección remota. Para la dirección remota en sí, consulta Home Assistant fuera de casa en tu reloj.

Problemas al pegar

Un token que parece correcto puede no serlo, porque lo que has pegado no siempre es lo que te dio Home Assistant. Home Assistant compara el token carácter por carácter, así que un solo carácter de más o de menos es un token no válido y un 401. Los culpables habituales:

El remedio es el mismo para todos: vuelve a copiar el token con el botón de copiar del cuadro de diálogo y pégalo directamente. Si el cuadro de diálogo ya está cerrado, el token se ha perdido; crea uno nuevo y elimina la entrada antigua.

Lo que AmazHA limpia y lo que rechaza

AmazHA resuelve por su cuenta los casos que tienen arreglo, tanto al guardar el token como cuando el móvil lo vuelve a leer para hacer una petición:

• Se eliminan: espacios, saltos de línea, caracteres de ancho cero, espacios de no separación, marcas de orden de bytes, guiones suaves y marcas de dirección, en cualquier parte del token. Ninguno de ellos puede formar parte de un token de Home Assistant, que se compone de letras, cifras, -, _ y puntos.
• Se quitan de los extremos: las comillas rectas y tipográficas, los acentos graves y las comillas angulares.
• Se descarta al principio: un Bearer pegado (en mayúsculas o minúsculas), porque AmazHA añade esa palabra por su cuenta.

Lo que la limpieza no puede arreglar es un carácter visible que ningún token contiene, normalmente los … de una copia que quedó cortada. AmazHA no adivina: se niega a enviar ese token, así que ninguna petición llega a Home Assistant y no se cuenta ningún inicio de sesión fallido. La pantalla Home Assistant de los ajustes muestra Token no válido, con la explicación «El token contiene un carácter que un token de Home Assistant no puede tener — suele ser una copia cortada (…). Vuelve a copiar el token completo desde tu perfil de Home Assistant › Seguridad y pégalo arriba.» El reloj muestra Revisa el token · «Tiene un carácter no válido — pégalo de nuevo». Es el paso 6 de Cuando algo falla.

Mantenlo seguro

Trata cada token de larga duración como una contraseña que no caduca en 10 años: un token por app, un nombre que diga de qué app es, y elimínalo el día que dejes de usar esa app. En concreto:

• Un token por app o dispositivo. Si das el mismo token a tres programas, no puedes revocar uno sin romper los otros dos, ni saber cuál de ellos está llamando.
• Ponle el nombre de la app. «AmazHA», «Script de copia de seguridad», «Tablet de la pared». El nombre es lo único que verás después en la lista; el token en sí no se vuelve a mostrar.
• Revisa la lista de vez en cuando. Cada entrada muestra cuándo se creó y, una vez usada, cuándo y desde dónde se usó por última vez. Un token que nadie ha usado en meses es candidato a eliminarse.
• Revoca eliminando. En la pestaña Seguridad, elimina el token por su nombre. La app que lo usaba falla en su siguiente petición, con un 401; no se toca nada más.
• Si un token puede haberse filtrado, elimínalo y crea uno nuevo. Eliminar es la única forma de revocar un solo token; el sustituto se pone en la app en un minuto.
• Nunca pegues un token en una solicitud de soporte, una publicación de un foro o una captura de pantalla. El diagnóstico de una buena app nunca lo necesita.

Eliminar todos los tokens de actualización desde la misma pestaña cierra la sesión en tus dispositivos, pero mantiene la sesión actual y tus tokens de larga duración, como indica el cuadro de confirmación de Home Assistant. Los tokens de larga duración se revocan uno por uno.

En AmazHA

AmazHA necesita exactamente un token de larga duración, de un administrador, introducido una vez en los ajustes de AmazHA dentro de la app Zepp; ese único token sirve para la dirección local y para la remota, y se queda en tu móvil. Los campos de conexión están disponibles una vez desbloqueada la versión completa (un desbloqueo único, sin suscripción: consulta Desbloquea la versión completa). Después:

1. Crea el token como administrador, como se ha explicado (pasos 1–3 de Conecta Home Assistant).
2. En la app Zepp, ve a Perfil › tu reloj › Apps › AmazHA › Ajustes y toca Home Assistant (paso 4).
3. Introduce tu dirección de casa en URL local (LAN), por ejemplo http://192.168.1.50:8123, y, si quieres que el reloj funcione también fuera de casa, la dirección exterior en URL remota. Cualquiera de los dos campos puede quedarse vacío.
4. Pega el token en Token de acceso de larga duración (paso 7).
5. Toca Conectar. Con las dos direcciones configuradas, el resultado muestra cada una, LAN y Remota; con una sola dirección indica Conectado ✓. Si el token no es de un administrador, aparece debajo la línea ámbar descrita arriba.

Un token, dos direcciones

No necesitas un segundo token para la dirección remota. Un token pertenece a un usuario, no a una dirección: el mismo token es válido tanto si la petición llega a Home Assistant por tu wifi como desde fuera. En casa, AmazHA usa la dirección local; la remota solo sirve para cuando el móvil está fuera. La única excepción es el usuario con Local access only descrito arriba, cuyo token se rechaza desde fuera por diseño.

Adónde va el token y adónde no

El reloj nunca habla directamente con Home Assistant. Lo hace tu móvil, a través de la app Zepp, y el token se guarda ahí, en el móvil. Solo se envía a tu servidor de Home Assistant, en la cabecera Authorization de las peticiones del propio móvil; nunca se envía al reloj, que solo recibe lo que muestra por su enlace Bluetooth con el móvil. AmazHA no tiene ningún servidor propio por el que pueda pasar el token, y el informe de soporte nunca lo incluye.

Lo que hace el móvil con el token, petición por petición:

La última fila es la función de sensores del reloj, que envía a Home Assistant la frecuencia cardíaca, los pasos, la batería y más de tu Amazfit como un dispositivo de la integración Mobile App: Envía los datos de tu Amazfit a Home Assistant lo explica.

Cuando AmazHA dice algo del token

El pequeño código bajo Sin conexión está ahí para el soporte: si nos escribes, una foto del reloj dice exactamente qué ha fallado. Para cualquier otro mensaje que pueda mostrar el reloj, consulta Cuando algo falla.