Token di accesso a lungo termine di Home Assistant: crearlo, perché admin, e “funziona ma non mostra nulla”

La risposta breve

Un token di accesso a lungo termine (lo trovi cercato anche come token di accesso a lunga durata) è un sostituto della password per app e script: lo crei nel tuo profilo di Home Assistant, nella scheda Sicurezza, sotto Token di accesso a lungo termine, e Home Assistant lo mostra una volta sola. È valido per 10 anni. Alcune app hanno bisogno del token di un amministratore, perché alcune parti dell’API, come /api/template, rifiutano ogni altro utente con un 401.

Il resto dell’articolo affronta ogni aspetto: cos’è il token, dove trovarlo, come copiarlo senza romperlo, perché la questione dell’amministratore conta, come provare un token con due comandi curl e come tenere sotto controllo i token. L’esempio concreto è AmazHA, un’app per Amazfit dedicata a Home Assistant, perché tocca ognuno di questi punti: le serve un token, le serve il token di un amministratore, e deve gestire token che arrivano rovinati da un copia e incolla.

Cos’è un token di accesso a lungo termine

Un token di accesso a lungo termine è una credenziale che permette a un programma di agire come il tuo utente Home Assistant senza passare dalla schermata di accesso. Quando accedi all’interfaccia web, Home Assistant consegna al browser un token di accesso breve (30 minuti) e un refresh token che lo rinnova. Uno script, un’app per il telefono o per l’orologio non può eseguire facilmente quel flusso di accesso, quindi Home Assistant offre un secondo tipo di token: uno che crei a mano, copi una volta e dai al programma.

In pratica contano tre proprietà:

• È valido per 10 anni. La documentazione dell’API di autenticazione di Home Assistant dice che i token a lungo termine “are valid for 10 years”, e la pagina del profilo lo ripete: ogni token è valido per 10 anni dalla creazione.
• Viene mostrato una volta sola. Home Assistant non conserva il token in sé, quindi non può mostrarlo di nuovo. Se lo perdi, ne crei uno nuovo.
• È l’utente che l’ha creato. Un token porta i permessi dell’utente che l’ha creato, né più né meno. Un token creato da un amministratore è un amministratore per ogni richiesta che firma; un token creato da un utente normale è un utente normale.

Il token viaggia in un’intestazione HTTP a ogni richiesta:

Authorization: Bearer <your token>

È tutto ciò che un client deve fare. Non c’è nome utente, non c’è password e non c’è sessione: ogni richiesta con un token valido in quell’intestazione viene accettata come quell’utente.

Dove trovarlo

I token di accesso a lungo termine si creano nel tuo profilo utente, nella scheda Sicurezza. Nell’app di Home Assistant o in un browser:

1. Apri la barra laterale (il menu ≡ sul telefono) e tocca il tuo nome in fondo.
2. Nel tuo profilo, apri la scheda Sicurezza.
3. Più in basso in quella scheda c’è la sezione Token di accesso a lungo termine, con l’elenco dei token che hai già e un pulsante Crea token.

La documentazione utente di Home Assistant lo descrive allo stesso modo: User profile › Security, la pagina in cui cambi anche la password, configuri l’autenticazione a più fattori e gestisci i refresh token.

“Non lo trovo”

Il motivo più comune è la scheda. Il profilo si apre sulle impostazioni generali (lingua, tema e simili); la sezione dei token è nella scheda Sicurezza. Molte guide più vecchie dicono di scorrere fino in fondo alla pagina del profilo, cosa vera prima che il profilo fosse diviso in schede.

Altri due motivi:

• Stai cercando il token di qualcun altro. Ogni utente vede e gestisce solo i propri token. Un token creato da un’altra persona della famiglia non compare nel tuo profilo, e non puoi eliminarlo da lì.
• Hai effettuato l’accesso con un utente diverso da quello che pensi. Controlla il nome in fondo alla barra laterale. Se un’app ha bisogno del token di un amministratore (ne parliamo più sotto), assicurati che quel nome appartenga a un amministratore prima di crearlo.

Crealo e copialo

Creare un token richiede quattro tocchi; è nel copiarlo correttamente che le cose vanno storte. I passaggi:

1. Nella scheda Sicurezza, sotto Token di accesso a lungo termine, tocca Crea token.
2. Home Assistant ti chiede di dare un nome al token. Usa il nome dell’app, per esempio AmazHA. I nomi devono essere unici tra i tuoi token.
3. La finestra successiva mostra il token con l’avviso di copiarlo subito, perché non verrà più mostrato. Copialo adesso, per intero.
4. Chiudi la finestra. Il token ora compare nell’elenco con il suo nome e il giorno in cui è stato creato.

Un token è una lunga stringa di lettere, cifre, - e _, in tre parti separate da punti. La sua lunghezza è il motivo della maggior parte dei problemi di copia: non sta su una riga, quindi una selezione distratta ne prende solo una parte, e alcune app accorciano una stringa lunga sullo schermo con i puntini di sospensione (…) e poi copiano ciò che mostrano.

Abitudini pratiche che evitano guai:

• Usa il pulsante di copia della finestra, non una selezione manuale.
• Incollalo direttamente nell’app che ne ha bisogno. Una deviazione attraverso una chat, un’email o un’app di note può aggiungere caratteri invisibili, virgolette tipografiche o a capo.
• Non aggiungere Bearer davanti, a meno che l’app non chieda esplicitamente l’intera intestazione. Quasi ogni app aggiunge quella parola da sola.
• Se ti serve su un altro dispositivo, crea lì un secondo token invece di far girare il primo.

Perché alcune app hanno bisogno del token di un amministratore

Alcune app hanno bisogno del token di un amministratore perché Home Assistant riserva alcuni endpoint dell’API agli amministratori, e un token può fare solo ciò che può fare il suo utente. L’esempio più chiaro è l’endpoint dei template, POST /api/template, che esegue un template Jinja sul server e restituisce il risultato.

Nel codice sorgente di Home Assistant, la vista che lo serve, APITemplateView in homeassistant/components/api/__init__.py, ha il suo metodo post decorato con @require_admin. Quel decoratore controlla l’utente dietro il token; se non è un amministratore solleva Unauthorized, che lo strato HTTP di Home Assistant trasforma in 401 Unauthorized. Anche la documentazione della REST API marca l’endpoint come “Admin”.

Non è l’unico. La REST API si divide più o meno così:

E allora perché un’app dovrebbe aver bisogno dell’endpoint dei template? Perché alcune informazioni non sono negli endpoint REST semplici. Il caso più chiaro sono le aree: /api/states restituisce ogni entità con il suo stato e i suoi attributi, ma non l’area a cui appartiene, e la REST API non ha un endpoint che elenchi le aree. Un template può chiederle: area_id(entity_id) e area_name(...) restituiscono l’area che Home Assistant risolve per ogni entità, tramite l’impostazione dell’entità stessa o quella del suo dispositivo. Un’app che vuole mostrare la tua casa stanza per stanza, come fanno le plance di Home Assistant, esegue quindi un template, e per farlo ha bisogno di un amministratore.

Dare diritti di amministratore a un’app è una buona idea?

Il consiglio sulla sicurezza di Home Assistant è di dare l’accesso da amministratore solo agli account che ne hanno bisogno. Un’app che ha bisogno di /api/template è uno di questi casi, e hai due modi ragionevoli di gestirlo:

• Crea il token con il tuo utente amministratore. L’opzione più semplice. Il token compare nel tuo profilo con il suo nome, ed eliminarlo revoca solo quell’app.
• Crea un utente amministratore separato per l’app in Impostazioni › Persone, accedi una volta con quell’utente e crea lì il token. Le sue informazioni di “ultimo utilizzo” restano separate dalle tue, e più avanti puoi disattivare l’intero utente. Tienilo attivo finché l’app lo usa: i token di un utente disattivato smettono di funzionare. Non attivare Local access only (solo accesso locale) se l’app si collega anche da fuori casa, per il motivo spiegato nella sezione sul 401 più sotto.

In entrambi i casi, il token merita la cura che dai a una password: il token di un amministratore può fare tutto ciò che puoi fare tu in Home Assistant.

“Funziona ma non mostra nulla”: il 401 su /api/template

Quando un’app si collega correttamente e comunque non mostra nulla, la causa è quasi sempre un token di un utente che non è amministratore. Il test di connessione riesce, perché la maggior parte delle app prova con GET /api/ e quell’endpoint accetta qualsiasi token valido. Anche gli stati si possono leggere. Fallisce solo la richiesta del template, con un 401, e un’app che costruisce il suo elenco di dispositivi da quel template finisce senza nulla da mostrare.

La sequenza, dal punto di vista dell’app:

1. GET /api/ con il token: 200, {"message": "API running."}. L’app segnala “connesso”.
2. GET /api/states/...: 200. Gli stati ci sono.
3. POST /api/template per associare le entità alle aree: 401. Niente aree, quindi niente stanze, quindi uno schermo vuoto.

Ciò che confonde è che nient’altro sembra sbagliato. L’indirizzo è giusto, il token è valido, Home Assistant è attivo. Persino le azioni possono funzionare: POST /api/services/... è aperto agli utenti normali, quindi con lo stesso token si può ancora accendere una luce dall’app.

Cosa mostra Home Assistant

Home Assistant conta ogni 401 che invia come un accesso fallito, compreso quello del controllo admin. Il suo log riceve un avviso che inizia con “Login attempt or request with invalid authentication from …”, con l’indirizzo da cui è arrivata la richiesta (a casa, di solito il tuo telefono o il tuo server), e l’interfaccia web mostra una notifica Login attempt failed. Se hai attivato il blocco degli IP con un numero di tentativi di accesso prima del ban, abbastanza 401 di questo tipo bannano quell’indirizzo: da quel momento riceve 403 Forbidden per tutto, finché non lo rimuovi da ip_bans.yaml e riavvii Home Assistant.

Quindi, se vedi ripetute notifiche “Login attempt failed” che puntano al tuo telefono, un’app con il token di un utente normale che chiama un endpoint riservato agli admin è una delle spiegazioni, oltre a un token che è stato eliminato.

Come AmazHA lo rileva e come lo dice

AmazHA, che legge le tue aree tramite /api/template, controlla questo caso di proposito invece di lasciarti con un orologio vuoto:

• Quando tocchi Connetti, il telefono controlla prima l’indirizzo con GET /api/, poi invia un template banale, {{ 1 }}, a /api/template. Se quel template viene rifiutato con un 401, un 403 o un 400, il token viene segnalato come non di un amministratore. La schermata Home Assistant mostra allora Connesso ✓ con una riga ambra sotto: “Connesso, ma questo token non ha permessi da amministratore, quindi l’orologio non può caricare le tue entità. Genera un token a lunga scadenza da un utente di Home Assistant con ruolo Administrator e incollalo qui sopra.”
• Sull’orologio, quando le stanze non si possono caricare perché il template delle aree viene rifiutato, la home mostra il banner Serve un token admin · “Il token non ha permessi admin — usa un utente amministratore di Home Assistant”, invece di un generico Offline.
• Nel rapporto di supporto che puoi inviare dalle impostazioni di AmazHA, una riga “HA token” dice se il token è stato riconosciuto come quello di un amministratore, senza mai includere il token.

La soluzione è la stessa in ogni caso: crea un nuovo token a lungo termine dopo aver effettuato l’accesso come amministratore, incollalo e tocca di nuovo Connetti. Il passo 5 di Quando qualcosa non va lo mostra nel video.

Come verificare che un utente sia amministratore

Apri Impostazioni › Persone, poi la scheda Utenti. Per un amministratore la colonna Gruppo dice Amministratori; aprendo un utente compare l’interruttore Amministratore (gli amministratori possono gestire utenti, dispositivi, automazioni e plance).

C’è una prova più rapida: se nella barra laterale dell’account con cui hai effettuato l’accesso non c’è affatto la voce Impostazioni, quell’utente non è amministratore. Home Assistant registra il suo pannello di configurazione come riservato agli admin, quindi gli utenti normali non lo vedono mai. In quel caso, esci, accedi come amministratore e crea lì il token.

Verificalo da solo con curl

Puoi provare qualsiasi token in un minuto da un computer sulla stessa rete, con due comandi curl: uno su /api/, che ogni token valido supera, e uno su /api/template, che supera solo il token di un amministratore. Gli esempi usano 192.168.1.50:8123 come indirizzo di Home Assistant; sostituiscilo con il tuo. Funzionano così come sono in un terminale macOS o Linux.

Per tenere il token fuori dalla cronologia della shell, leggilo prima in una variabile. Incolla il token quando il comando resta in attesa, poi premi Invio:

read -rs HA_TOKEN

Prova 1: il token è valido?

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

Un token valido risponde {"message":"API running."} e HTTP 200. Attento alla barra finale: l’endpoint è /api/, non /api.

Prova 2: il token è di un amministratore?

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

Il token di un amministratore riceve il template eseguito, 1, e HTTP 200. Il token di un utente normale riceve HTTP 401.

Come leggere insieme i due risultati:

Due avvertenze. Primo, questo prova il token dal tuo computer; un’app sul telefono può seguire un percorso diverso verso Home Assistant, soprattutto fuori casa. Secondo, superare solo la prova 1 dimostra ben poco per le app che hanno bisogno delle aree: è esattamente la prova che il token di un utente normale supera.

Il 401 di “Local access only”

Un utente con Local access only attivo può accedere solo dalla tua rete locale, e Home Assistant applica la stessa regola ai token di quell’utente. Una richiesta da un indirizzo fuori dalla tua rete, o che arriva tramite Home Assistant Cloud, viene rifiutata con un 401, anche se lo stesso token funziona perfettamente a casa. Se un’app funziona sul tuo Wi-Fi e fallisce con un 401 fuori casa, apri l’utente in Impostazioni › Persone e controlla quell’interruttore prima di sospettare dell’indirizzo remoto. Per l’indirizzo remoto in sé, vedi Home Assistant fuori casa sul tuo orologio.

Problemi di incolla

Un token che sembra giusto può comunque essere sbagliato, perché ciò che hai incollato non è sempre ciò che Home Assistant ti ha dato. Home Assistant confronta il token carattere per carattere, quindi un solo carattere in più o in meno è un token non valido e un 401. I colpevoli abituali:

Il rimedio è lo stesso per tutti: copia di nuovo il token con il pulsante di copia della finestra e incollalo direttamente. Se la finestra è già chiusa, il token è perso; creane uno nuovo ed elimina la vecchia voce.

Cosa ripulisce AmazHA, e cosa rifiuta

AmazHA gestisce da sola i casi risolvibili, sia quando salvi il token sia di nuovo quando il telefono lo legge per fare una richiesta:

• Rimossi: spazi, a capo, caratteri a larghezza zero, spazi unificatori, byte-order mark, trattini morbidi e segni di direzione, in qualsiasi punto del token. Nessuno di questi può far parte di un token di Home Assistant, che è fatto di lettere, cifre, -, _ e punti.
• Tolti dalle estremità: virgolette dritte e tipografiche, backtick e caporali.
• Eliminato dall’inizio: un Bearer incollato (con qualsiasi combinazione di maiuscole), perché AmazHA aggiunge quella parola da sola.

Ciò che la pulizia non può correggere è un carattere visibile che nessun token contiene, tipicamente i … di una copia tagliata. AmazHA non tira a indovinare: si rifiuta del tutto di inviare quel token, quindi nessuna richiesta raggiunge Home Assistant e non viene contato nessun accesso fallito. La schermata Home Assistant nelle impostazioni mostra Token non valido, con la spiegazione “Il token contiene un carattere che un token di Home Assistant non può avere — di solito è una copia tagliata (…). Copia di nuovo il token completo dal tuo profilo di Home Assistant › Sicurezza e incollalo qui sopra.” L’orologio mostra Controlla il token · “Contiene un carattere non valido — incollalo di nuovo”. È il passo 6 di Quando qualcosa non va.

Tienilo al sicuro

Tratta ogni token a lungo termine come una password che non scade per 10 anni: un token per app, un nome che dice di quale app si tratta, ed eliminalo il giorno in cui smetti di usare quell’app. In concreto:

• Un token per app o dispositivo. Se dai lo stesso token a tre programmi, non puoi revocarne uno senza rompere gli altri due, e non puoi sapere quale dei tre sta chiamando.
• Dagli il nome dell’app. “AmazHA”, “Script di backup”, “Tablet a muro”. Il nome è tutto ciò che vedrai poi nell’elenco; il token in sé non viene mai più mostrato.
• Dai un’occhiata all’elenco ogni tanto. Ogni voce mostra quando è stata creata e, una volta usata, quando e da dove è stata usata l’ultima volta. Un token che nessuno usa da mesi è un candidato all’eliminazione.
• Revoca eliminando. Nella scheda Sicurezza, elimina il token per nome. L’app che lo usava fallisce alla richiesta successiva, con un 401; nient’altro viene toccato.
• Se un token potrebbe essere trapelato, eliminalo e creane uno nuovo. Eliminare è l’unico modo per revocare un singolo token; il sostituto va nell’app in un minuto.
• Non incollare mai un token in una richiesta di supporto, un post su un forum o uno screenshot. La diagnostica di una buona app non ne ha mai bisogno.

Eliminare tutti i refresh token dalla stessa scheda disconnette i tuoi dispositivi ma lascia al loro posto la sessione corrente e i tuoi token a lungo termine, come dice la finestra di conferma di Home Assistant. I token a lungo termine si revocano uno per uno.

In AmazHA

AmazHA ha bisogno di un solo token a lungo termine, di un amministratore, inserito una volta nelle impostazioni di AmazHA dentro l’app Zepp; quell’unico token serve sia l’indirizzo locale sia quello remoto, e resta sul tuo telefono. I campi di connessione sono disponibili dopo lo sblocco della versione completa (uno sblocco una tantum, senza abbonamento: vedi Sblocca la versione completa). Poi:

1. Crea il token come amministratore, come sopra (passi 1–3 di Collega Home Assistant).
2. Nell’app Zepp, vai su Profilo › il tuo orologio › App › AmazHA › Impostazioni, poi tocca Home Assistant (passo 4).
3. Inserisci il tuo indirizzo di casa in URL locale (LAN), per esempio http://192.168.1.50:8123, e, se vuoi che l’orologio funzioni anche fuori casa, l’indirizzo esterno in URL remoto. Uno dei due campi può restare vuoto.
4. Incolla il token in Token di accesso a lunga scadenza (passo 7).
5. Tocca Connetti. Con entrambi gli indirizzi impostati, il risultato li mostra uno per uno, LAN e Remoto; con un solo indirizzo indica Connesso ✓. Se il token non è di un amministratore, sotto compare la riga ambra descritta sopra.

Un token, due indirizzi

Non ti serve un secondo token per l’indirizzo remoto. Un token appartiene a un utente, non a un indirizzo: lo stesso token è valido sia che la richiesta raggiunga Home Assistant dal tuo Wi-Fi sia da fuori. A casa AmazHA usa l’indirizzo locale; quello remoto serve solo quando il telefono è lontano. L’unica eccezione è l’utente con Local access only descritto sopra, il cui token viene rifiutato da fuori per scelta.

Dove va il token, e dove no

L’orologio non parla mai direttamente con Home Assistant. Lo fa il telefono, tramite l’app Zepp, e il token è conservato lì, sul telefono. Viene inviato solo al tuo server Home Assistant, nell’intestazione Authorization delle richieste del telefono stesso; non viene mai inviato all’orologio, che riceve solo ciò che mostra tramite il suo collegamento Bluetooth con il telefono. AmazHA non ha un proprio server da cui il token possa passare, e il rapporto di supporto non lo include mai.

Cosa fa il telefono con il token, richiesta per richiesta:

L’ultima riga è la funzione dei sensori dell’orologio, che invia a Home Assistant la frequenza cardiaca, i passi, la batteria e altro del tuo Amazfit come dispositivo dell’integrazione Mobile App: ne parla Invia i dati del tuo Amazfit a Home Assistant.

Quando AmazHA dice qualcosa sul token

Il piccolo codice sotto Offline serve al supporto: se ci scrivi, una foto dell’orologio dice esattamente cosa non ha funzionato. Per ogni altro messaggio che l’orologio può mostrare, vedi Quando qualcosa non va.