Jeton d’accès longue durée Home Assistant : le créer, pourquoi admin, et « ça marche mais rien ne s’affiche »

La réponse courte

Un jeton d’accès longue durée remplace un mot de passe pour les apps et les scripts : vous le créez dans votre profil Home Assistant, dans l’onglet Sécurité, sous Jetons d’accès longue durée, et Home Assistant ne l’affiche qu’une seule fois. Il est valable 10 ans. Certaines apps ont besoin du jeton d’un administrateur, parce que des parties de l’API, comme /api/template, refusent tout autre utilisateur avec un 401.

La suite de cet article reprend chaque point : ce qu’est le jeton, où le trouver, comment le copier sans l’abîmer, pourquoi la question de l’administrateur compte, comment tester un jeton avec deux commandes curl, et comment garder vos jetons sous contrôle. L’exemple concret est AmazHA, une app Home Assistant pour montres Amazfit, parce qu’elle touche chacun de ces points : elle a besoin d’un jeton, du jeton d’un administrateur, et elle doit composer avec des jetons abîmés par un copier-coller.

Ce qu’est un jeton d’accès longue durée

Un jeton d’accès longue durée est un identifiant qui permet à un programme d’agir en tant que votre utilisateur Home Assistant sans passer par l’écran de connexion. Quand vous vous connectez à l’interface web, Home Assistant remet à votre navigateur un jeton d’accès court (30 minutes) et un jeton de rafraîchissement qui le renouvelle. Un script, une app de téléphone ou une app de montre ne peut pas facilement suivre ce processus de connexion : Home Assistant propose donc un second type de jeton, que vous créez à la main, copiez une fois et donnez au programme.

Trois propriétés comptent en pratique :

• Il est valable 10 ans. La documentation de l’API d’authentification de Home Assistant indique que les jetons longue durée « sont valables 10 ans », et la page du profil le répète : chaque jeton est valable 10 ans à partir de sa création.
• Il n’est affiché qu’une fois. Home Assistant ne conserve pas le jeton lui-même : il ne peut donc pas le réafficher. Si vous le perdez, vous en créez un nouveau.
• Il est l’utilisateur qui l’a créé. Un jeton porte les droits de l’utilisateur qui l’a créé, ni plus ni moins. Un jeton créé par un administrateur est un administrateur pour chaque requête qu’il signe ; un jeton créé par un utilisateur ordinaire est un utilisateur ordinaire.

Le jeton voyage dans un en-tête HTTP à chaque requête :

Authorization: Bearer <your token>

C’est tout ce qu’un client doit faire. Pas de nom d’utilisateur, pas de mot de passe, pas de session : toute requête portant un jeton valide dans cet en-tête est acceptée comme venant de cet utilisateur.

Où le trouver

Vous créez les jetons d’accès longue durée dans votre propre profil utilisateur, dans l’onglet Sécurité. Dans l’app Home Assistant ou dans un navigateur :

1. Ouvrez la barre latérale (le menu ≡ sur un téléphone) et touchez votre nom, tout en bas.
2. Dans votre profil, ouvrez l’onglet Sécurité.
3. Plus bas dans cet onglet se trouve la section Jetons d’accès longue durée, avec la liste des jetons que vous avez déjà et un bouton Créer un jeton.

La documentation utilisateur de Home Assistant le décrit de la même façon : profil utilisateur › Sécurité, la page où vous changez aussi votre mot de passe, configurez l’authentification multifacteur et gérez les jetons de rafraîchissement.

« Je ne le trouve pas »

La raison la plus fréquente, c’est l’onglet. Le profil s’ouvre sur ses réglages généraux (langue, thème, etc.) ; la section des jetons est dans l’onglet Sécurité. Beaucoup d’anciens guides disent de faire défiler jusqu’en bas de la page du profil, ce qui était vrai avant que le profil soit découpé en onglets.

Deux autres raisons :

• Vous cherchez le jeton de quelqu’un d’autre. Chaque utilisateur ne voit et ne gère que ses propres jetons. Un jeton créé par une autre personne du foyer n’apparaît pas dans votre profil, et vous ne pouvez pas le supprimer depuis là.
• Vous êtes connecté avec un autre utilisateur que celui que vous croyez. Vérifiez le nom en bas de la barre latérale. Si une app a besoin du jeton d’un administrateur (on y revient plus bas), assurez-vous que ce nom est celui d’un administrateur avant de créer le jeton.

Le créer et le copier

Créer un jeton prend quatre touchers ; c’est en le copiant que les choses se gâtent. Les étapes :

1. Dans l’onglet Sécurité, sous Jetons d’accès longue durée, touchez Créer un jeton.
2. Home Assistant vous demande de donner un nom au jeton. Utilisez le nom de l’app, par exemple AmazHA. Les noms doivent être uniques parmi vos jetons.
3. La fenêtre suivante affiche le jeton, avec l’avertissement qu’il faut le copier maintenant parce qu’il ne sera plus affiché. Copiez-le tout de suite, en entier.
4. Fermez la fenêtre. Le jeton apparaît désormais dans la liste sous son nom, avec le jour de sa création.

Un jeton est une longue chaîne de lettres, de chiffres, de - et de _, en trois parties séparées par des points. Sa longueur est la raison de la plupart des problèmes de copie : il ne tient pas sur une ligne, si bien qu’une sélection imprécise n’en prend qu’une partie, et certaines apps raccourcissent une longue chaîne à l’écran avec des points de suspension (…), puis copient ce qu’elles affichent.

Des habitudes pratiques qui évitent les ennuis :

• Utilisez le bouton de copie de la fenêtre, pas une sélection à la main.
• Collez-le directement dans l’app qui en a besoin. Un détour par une messagerie, un e-mail ou une app de notes peut ajouter des caractères invisibles, des guillemets typographiques ou des retours à la ligne.
• N’ajoutez pas Bearer devant, sauf si l’app demande explicitement l’en-tête complet. Presque toutes les apps ajoutent ce mot elles-mêmes.
• Si vous en avez besoin sur un autre appareil, créez-y un second jeton au lieu de faire circuler le premier.

Pourquoi certaines apps ont besoin du jeton d’un administrateur

Certaines apps ont besoin du jeton d’un administrateur parce que Home Assistant réserve quelques points d’accès de l’API aux administrateurs, et qu’un jeton ne peut faire que ce que son utilisateur peut faire. L’exemple le plus net est le point d’accès des modèles, POST /api/template, qui rend un modèle Jinja sur le serveur et renvoie le résultat.

Dans le code source de Home Assistant, la vue qui le sert, APITemplateView dans homeassistant/components/api/__init__.py, a sa méthode post décorée par @require_admin. Ce décorateur vérifie l’utilisateur derrière le jeton ; s’il n’est pas administrateur, il lève Unauthorized, que la couche HTTP de Home Assistant transforme en 401 Unauthorized. La documentation de l’API REST marque elle aussi ce point d’accès « Admin ».

Ce n’est pas le seul. L’API REST se répartit à peu près ainsi :

Alors pourquoi une app aurait-elle besoin du point d’accès des modèles ? Parce que certaines informations ne figurent pas dans les simples points d’accès REST. Le cas le plus net, ce sont les pièces (les zones de Home Assistant) : /api/states renvoie chaque entité avec son état et ses attributs, mais pas la pièce à laquelle elle appartient, et l’API REST n’a aucun point d’accès qui liste les pièces. Un modèle peut les demander : area_id(entity_id) et area_name(...) renvoient la pièce que Home Assistant détermine pour chaque entité, d’après le réglage de l’entité elle-même ou celui de son appareil. Une app qui veut afficher votre maison pièce par pièce, comme le font les tableaux de bord de Home Assistant, rend donc un modèle, et il lui faut un administrateur pour cela.

Donner des droits d’administrateur à une app, est-ce une bonne idée ?

Les conseils de sécurité de Home Assistant recommandent de ne donner l’accès administrateur qu’aux comptes qui en ont besoin. Une app qui a besoin de /api/template est l’un de ces cas, et vous avez deux façons raisonnables de vous y prendre :

• Créez le jeton avec votre propre utilisateur administrateur. L’option la plus simple. Le jeton figure dans votre profil sous son nom, et le supprimer révoque cette seule app.
• Créez un utilisateur administrateur distinct pour l’app dans Paramètres › Personnes, connectez-vous une fois avec cet utilisateur et créez-y le jeton. Ses informations de « dernière utilisation » restent séparées des vôtres, et vous pouvez désactiver l’utilisateur entier plus tard. Gardez-le actif tant que l’app l’utilise : les jetons d’un utilisateur désactivé cessent de fonctionner. Ne cochez pas Local access only (accès local uniquement) si l’app se connecte aussi depuis l’extérieur, pour la raison expliquée dans la section sur le 401 plus bas.

Dans les deux cas, le jeton mérite le même soin qu’un mot de passe : le jeton d’un administrateur peut faire tout ce que vous pouvez faire dans Home Assistant.

« Ça marche mais rien ne s’affiche » : le 401 sur /api/template

Quand une app se connecte avec succès et n’affiche pourtant rien, la cause est presque toujours le jeton d’un utilisateur qui n’est pas administrateur. Le test de connexion réussit, parce que la plupart des apps testent avec GET /api/ et que ce point d’accès accepte n’importe quel jeton valide. Les états se lisent aussi. Seule la requête de modèle échoue, avec un 401, et une app qui construit sa liste d’appareils à partir de ce modèle se retrouve sans rien à afficher.

La séquence, du point de vue de l’app :

1. GET /api/ avec le jeton : 200, {"message": "API running."}. L’app indique « connecté ».
2. GET /api/states/... : 200. Les états sont là.
3. POST /api/template pour associer les entités aux pièces : 401. Pas de pièces, donc pas de salles, donc un écran vide.

Ce qui rend la chose déroutante, c’est que rien d’autre ne semble anormal. L’adresse est bonne, le jeton est valide, Home Assistant fonctionne. Même les actions peuvent fonctionner : POST /api/services/... est ouvert aux utilisateurs ordinaires, si bien qu’une lumière peut encore être commandée depuis l’app avec le même jeton.

Ce qu’affiche Home Assistant

Home Assistant compte chaque 401 qu’il envoie comme une tentative de connexion échouée, y compris celui du contrôle administrateur. Son journal reçoit un avertissement qui commence par « Login attempt or request with invalid authentication from … », avec l’adresse d’où venait la requête (à la maison, en général votre téléphone ou votre serveur), et l’interface web affiche une notification Login attempt failed (tentative de connexion échouée). Si vous avez activé le bannissement d’IP avec un nombre de tentatives avant bannissement, suffisamment de ces 401 bannissent cette adresse : dès lors, elle reçoit 403 Forbidden pour tout, jusqu’à ce que vous la retiriez de ip_bans.yaml et redémarriez Home Assistant.

Donc, si vous voyez des notifications répétées de tentative de connexion échouée qui désignent votre propre téléphone, une app munie du jeton d’un utilisateur ordinaire et appelant un point d’accès réservé aux administrateurs est une explication possible, à côté d’un jeton supprimé.

Comment AmazHA le détecte et le formule

AmazHA, qui lit vos pièces via /api/template, vérifie ce cas exprès au lieu de vous laisser avec une montre vide :

• Quand vous touchez Connecter, le téléphone vérifie d’abord l’adresse avec GET /api/, puis envoie un modèle trivial, {{ 1 }}, à /api/template. Si ce modèle est refusé avec un 401, un 403 ou un 400, le jeton est signalé comme n’étant pas celui d’un administrateur. L’écran Home Assistant affiche alors Connecté ✓ avec une ligne orange en dessous : « Connecté, mais ce jeton n’a pas les droits d’administrateur, donc la montre ne peut pas charger vos entités. Créez un jeton de longue durée depuis un utilisateur Home Assistant ayant le rôle Administrator et collez-le ci-dessus. »
• Sur la montre, quand les pièces ne peuvent pas être chargées parce que le modèle des pièces est refusé, l’accueil affiche la bannière Jeton admin requis · « Votre jeton n’a pas les droits admin — utilisez un utilisateur admin Home Assistant », au lieu d’un Hors ligne générique.
• Dans le rapport d’assistance que vous pouvez envoyer depuis les réglages d’AmazHA, une ligne « HA token » indique si le jeton a été reconnu comme celui d’un administrateur, sans jamais inclure le jeton.

La solution est la même dans tous les cas : créez un nouveau jeton longue durée en étant connecté comme administrateur, collez-le, touchez à nouveau Connecter. L’étape 5 de En cas de problème le montre en vidéo.

Comment vérifier qu’un utilisateur est administrateur

Ouvrez Paramètres › Personnes, puis l’onglet Utilisateurs. La colonne Groupe indique Administrateurs pour un administrateur ; ouvrir un utilisateur montre l’interrupteur Administrateur, dont la description précise que les administrateurs peuvent gérer les utilisateurs, les appareils, les automatisations et les tableaux de bord.

Il existe un test plus rapide : si la barre latérale du compte avec lequel vous êtes connecté n’a aucune entrée Paramètres, cet utilisateur n’est pas administrateur. Home Assistant enregistre son panneau de configuration comme réservé aux administrateurs : les utilisateurs ordinaires ne le voient donc jamais. Dans ce cas, déconnectez-vous, connectez-vous comme administrateur et créez-y le jeton.

Vérifiez-le vous-même avec curl

Vous pouvez tester n’importe quel jeton en une minute depuis un ordinateur du même réseau, avec deux commandes curl : l’une sur /api/, que tout jeton valide passe, l’autre sur /api/template, que seul le jeton d’un administrateur passe. Les exemples utilisent 192.168.1.50:8123 comme adresse de Home Assistant ; remplacez-la par la vôtre. Elles fonctionnent telles quelles dans un terminal macOS ou Linux.

Pour garder le jeton hors de l’historique de votre shell, lisez-le d’abord dans une variable. Collez le jeton quand la commande attend, puis appuyez sur Entrée :

read -rs HA_TOKEN

Test 1 : le jeton est-il valide ?

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

Un jeton valide répond {"message":"API running."} et HTTP 200. Attention à la barre oblique finale : le point d’accès est /api/, pas /api.

Test 2 : le jeton est-il celui d’un administrateur ?

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

Le jeton d’un administrateur reçoit le modèle rendu, 1, et HTTP 200. Le jeton d’un utilisateur ordinaire reçoit HTTP 401.

Comment lire les deux résultats ensemble :

Deux réserves. D’abord, ce test vérifie le jeton depuis votre ordinateur ; une app sur votre téléphone peut emprunter un autre chemin vers Home Assistant, surtout hors de chez vous. Ensuite, un test 1 réussi ne prouve pas grand-chose à lui seul pour les apps qui ont besoin des pièces : c’est exactement le test que le jeton d’un utilisateur ordinaire réussit.

Le 401 de « Local access only »

Un utilisateur pour qui Local access only (accès local uniquement) est activé ne peut se connecter que depuis votre réseau local, et Home Assistant applique la même règle à ses jetons. Une requête venant d’une adresse extérieure à votre réseau, ou arrivant par Home Assistant Cloud, est refusée avec un 401, alors que le même jeton fonctionne parfaitement à la maison. Si une app fonctionne sur votre Wi-Fi et échoue avec un 401 hors de chez vous, ouvrez l’utilisateur dans Paramètres › Personnes et regardez cet interrupteur avant de soupçonner l’adresse distante. Pour l’adresse distante elle-même, voir Home Assistant hors de chez vous sur votre montre.

Les problèmes de collage

Un jeton qui semble correct peut quand même être faux, parce que ce que vous avez collé n’est pas toujours ce que Home Assistant vous a donné. Home Assistant compare le jeton caractère par caractère : un seul caractère en trop ou en moins donne un jeton invalide et un 401. Les coupables habituels :

Le remède est le même pour tous : copiez à nouveau le jeton avec le bouton de copie de la fenêtre et collez-le directement. Si la fenêtre est déjà fermée, le jeton est perdu ; créez-en un nouveau et supprimez l’ancienne entrée.

Ce qu’AmazHA nettoie, et ce qu’elle refuse

AmazHA gère elle-même les cas réparables, à la fois quand vous enregistrez le jeton et à nouveau quand le téléphone le lit pour faire une requête :

• Supprimés : les espaces, les retours à la ligne, les caractères sans chasse, les espaces insécables, les marques d’ordre des octets, les traits d’union conditionnels et les marques de direction, n’importe où dans le jeton. Aucun d’eux ne peut faire partie d’un jeton Home Assistant, qui se compose de lettres, de chiffres, de -, de _ et de points.
• Retirés aux extrémités : les guillemets droits et typographiques, les accents graves et les guillemets français.
• Supprimé au début : un Bearer collé (quelle que soit la casse), parce qu’AmazHA ajoute ce mot elle-même.

Ce que le nettoyage ne peut pas réparer, c’est un caractère visible qu’aucun jeton ne contient, typiquement le … d’une copie tronquée. AmazHA ne devine pas : elle refuse purement et simplement d’envoyer ce jeton, si bien qu’aucune requête n’atteint Home Assistant et qu’aucune connexion échouée n’est comptée. L’écran Home Assistant des réglages affiche Jeton non valide, avec l’explication « Le jeton contient un caractère qu’un jeton Home Assistant ne peut pas contenir — le plus souvent une copie tronquée (…). Copiez à nouveau le jeton complet depuis votre profil Home Assistant › Sécurité et collez-le ci-dessus. » La montre affiche Vérifiez le jeton · « Il contient un caractère invalide — recollez-le ». C’est l’étape 6 de En cas de problème.

Le garder en sécurité

Traitez chaque jeton longue durée comme un mot de passe qui n’expire pas avant 10 ans : un jeton par app, un nom qui dit de quelle app il s’agit, et supprimez-le le jour où vous cessez d’utiliser cette app. Concrètement :

• Un jeton par app ou par appareil. Si vous donnez le même jeton à trois programmes, vous ne pouvez pas en révoquer un sans casser les deux autres, et vous ne pouvez pas savoir lequel appelle.
• Nommez-le d’après l’app. « AmazHA », « Script de sauvegarde », « Tablette murale ». Le nom est tout ce que vous verrez ensuite dans la liste ; le jeton lui-même n’est plus jamais affiché.
• Jetez un œil à la liste de temps en temps. Chaque entrée indique quand elle a été créée et, une fois utilisée, quand et d’où elle a été utilisée pour la dernière fois. Un jeton que personne n’a utilisé depuis des mois est un candidat à la suppression.
• Révoquez en supprimant. Dans l’onglet Sécurité, supprimez le jeton par son nom. L’app qui l’utilisait échoue à sa requête suivante, avec un 401 ; rien d’autre n’est touché.
• Si un jeton a pu fuiter, supprimez-le et créez-en un nouveau. La suppression est le seul moyen de révoquer un jeton en particulier ; le remplaçant se met dans l’app en une minute.
• Ne collez jamais un jeton dans une demande d’assistance, un message de forum ou une capture d’écran. Les diagnostics d’une app bien faite n’en ont jamais besoin.

Supprimer tous les jetons de rafraîchissement depuis le même onglet déconnecte vos appareils mais laisse en place la session en cours et vos jetons longue durée, comme l’indique la fenêtre de confirmation de Home Assistant. Les jetons longue durée se révoquent un par un.

Dans AmazHA

AmazHA a besoin d’exactement un jeton longue durée, d’un administrateur, saisi une seule fois dans les réglages d’AmazHA, dans l’app Zepp ; ce seul jeton sert à la fois pour l’adresse locale et pour l’adresse distante, et il reste sur votre téléphone. Les champs de connexion sont disponibles une fois la version complète débloquée (un déblocage unique, sans abonnement : voir Débloquer la version complète). Ensuite :

1. Créez le jeton en tant qu’administrateur, comme ci-dessus (étapes 1 à 3 de Connecter Home Assistant).
2. Dans l’app Zepp, allez dans Profil › votre montre › Applications › AmazHA › Paramètres, puis touchez Home Assistant (étape 4).
3. Saisissez votre adresse à la maison dans URL locale (LAN), par exemple http://192.168.1.50:8123, et, si vous voulez que la montre fonctionne aussi hors de chez vous, l’adresse extérieure dans URL distante. L’un ou l’autre champ peut rester vide.
4. Collez le jeton dans Jeton d’accès longue durée (étape 7).
5. Touchez Connecter. Avec les deux adresses, le résultat affiche chacune d’elles, LAN et Distant ; avec une seule adresse, il indique Connecté ✓. Si le jeton n’est pas celui d’un administrateur, la ligne orange décrite plus haut apparaît en dessous.

Un jeton, deux adresses

Vous n’avez pas besoin d’un second jeton pour l’adresse distante. Un jeton appartient à un utilisateur, pas à une adresse : le même jeton est valide que la requête atteigne Home Assistant par votre Wi-Fi ou depuis l’extérieur. À la maison, AmazHA utilise l’adresse locale ; l’adresse distante ne sert que quand le téléphone est ailleurs. La seule exception est l’utilisateur Local access only décrit plus haut, dont le jeton est refusé depuis l’extérieur par conception.

Où va le jeton, et où il ne va pas

La montre ne parle jamais directement à Home Assistant. C’est votre téléphone qui le fait, par l’app Zepp, et c’est là, sur le téléphone, que le jeton est conservé. Il n’est envoyé qu’à votre serveur Home Assistant, dans l’en-tête Authorization des propres requêtes du téléphone ; il n’est jamais envoyé à la montre, qui ne reçoit que ce qu’elle affiche, par sa liaison Bluetooth avec le téléphone. AmazHA n’a aucun serveur à elle par lequel le jeton transiterait, et le rapport d’assistance ne l’inclut jamais.

Ce que fait le téléphone avec le jeton, requête par requête :

La dernière ligne concerne la fonction des capteurs de la montre, qui envoie la fréquence cardiaque, les pas, la batterie et plus de votre Amazfit dans Home Assistant, sous forme d’appareil de l’intégration Mobile App : Envoyez les données de votre Amazfit à Home Assistant en parle.

Quand AmazHA vous parle du jeton

Le petit code sous Hors ligne est là pour l’assistance : si vous nous écrivez, une photo de la montre dit exactement ce qui a échoué. Pour tous les autres messages que la montre peut afficher, voir En cas de problème.