Долгосрочные токены доступа Home Assistant: как создать, почему нужен админ и «работает, но пусто»

Короткий ответ

Долгосрочный токен доступа — это замена пароля для приложений и скриптов: вы создаёте его в своём профиле Home Assistant, на вкладке Безопасность, в разделе Долгосрочные токены доступа, и Home Assistant показывает его только один раз. Он действует 10 лет. Некоторым приложениям нужен токен администратора, потому что части API, например /api/template, отказывают всем остальным пользователям с ошибкой 401.

Дальше в статье — по порядку: что такое токен, где его найти, как скопировать его, ничего не испортив, почему важен вопрос администратора, как проверить токен двумя командами curl и как держать токены под контролем. В качестве примера взят AmazHA — приложение Home Assistant для часов Amazfit, — потому что оно затрагивает все эти пункты: ему нужен токен, ему нужен токен администратора, и ему приходится справляться с токенами, испорченными при копировании и вставке.

Что такое долгосрочный токен доступа

Долгосрочный токен доступа — это учётные данные, которые позволяют программе действовать от имени вашего пользователя Home Assistant, не проходя через экран входа. Когда вы входите в веб-интерфейс, Home Assistant выдаёт браузеру короткий токен доступа (на 30 минут) и токен обновления, который его продлевает. Скрипту, приложению на телефоне или приложению для часов непросто пройти такой вход, поэтому Home Assistant предлагает второй вид токена: его создают вручную, копируют один раз и передают программе.

На практике важны три свойства:

• Он действует 10 лет. В документации по API аутентификации Home Assistant сказано, что долгосрочные токены «действительны 10 лет», и страница профиля это повторяет: каждый токен действует 10 лет с момента создания.
• Он показывается один раз. Home Assistant не хранит сам токен, поэтому не может показать его снова. Если вы его потеряли, создайте новый.
• Он равен пользователю, который его создал. Токен несёт права создавшего его пользователя — не больше и не меньше. Токен администратора — администратор для каждого запроса, который он подписывает; токен обычного пользователя — обычный пользователь.

Токен передаётся в HTTP-заголовке каждого запроса:

Authorization: Bearer <your token>

Больше клиенту ничего делать не нужно. Нет ни имени пользователя, ни пароля, ни сессии: любой запрос с действительным токеном в этом заголовке принимается как запрос этого пользователя.

Где его найти

Долгосрочные токены доступа создаются в вашем собственном профиле пользователя, на вкладке Безопасность. В приложении Home Assistant или в браузере:

1. Откройте боковую панель (меню ≡ на телефоне) и нажмите на своё имя внизу.
2. В профиле откройте вкладку Безопасность.
3. Ниже на этой вкладке находится раздел Долгосрочные токены доступа со списком уже созданных токенов и кнопкой Создать токен.

Пользовательская документация Home Assistant говорит то же самое: профиль пользователя › Безопасность — страница, где также меняют пароль, настраивают многофакторную аутентификацию и управляют токенами обновления.

«Не могу найти»

Чаще всего дело во вкладке. Профиль открывается на общих настройках (язык, тема и тому подобное); раздел токенов — на вкладке Безопасность. Во многих старых инструкциях сказано прокрутить страницу профиля до конца — так было, пока профиль не разделили на вкладки.

Ещё две причины:

• Вы ищете чужой токен. Каждый пользователь видит и управляет только своими токенами. Токен, который создал другой член семьи, в вашем профиле не появится, и удалить его оттуда нельзя.
• Вы вошли не под тем пользователем, под которым думаете. Проверьте имя внизу боковой панели. Если приложению нужен токен администратора (об этом ниже), убедитесь, что это имя принадлежит администратору, прежде чем создавать токен.

Создайте и скопируйте его

Создание токена занимает четыре нажатия; ошибки случаются при копировании. Шаги:

1. На вкладке Безопасность, в разделе Долгосрочные токены доступа, нажмите Создать токен.
2. Home Assistant попросит дать токену имя. Используйте название приложения, например AmazHA. Имена ваших токенов не должны повторяться.
3. Следующее окно показывает токен с предупреждением, что его нужно скопировать сейчас, потому что больше он показан не будет. Скопируйте его сразу и целиком.
4. Закройте окно. Теперь токен появится в списке под своим именем, с датой создания.

Токен — это длинная строка из букв, цифр, - и _, из трёх частей, разделённых точками. Именно длина — причина большинства проблем с копированием: он не помещается в одну строку, поэтому неаккуратное выделение захватывает только часть, а некоторые приложения сокращают длинную строку на экране многоточием (…) и копируют то, что показывают.

Практичные привычки, которые избавляют от проблем:

• Пользуйтесь кнопкой копирования в окне, а не выделением вручную.
• Вставляйте токен сразу в приложение, которому он нужен. Окольный путь через мессенджер, письмо или заметки может добавить невидимые символы, типографские кавычки или переносы строк.
• Не добавляйте Bearer перед токеном, если приложение явно не просит весь заголовок. Почти все приложения добавляют это слово сами.
• Если токен нужен на другом устройстве, создайте там второй токен, а не пересылайте первый.

Почему некоторым приложениям нужен токен администратора

Некоторым приложениям нужен токен администратора, потому что Home Assistant оставляет несколько точек API только для администраторов, а токен может лишь то, что может его пользователь. Самый наглядный пример — точка шаблонов, POST /api/template: она отрисовывает шаблон Jinja на сервере и возвращает результат.

В исходном коде Home Assistant представление, которое её обслуживает, — APITemplateView в homeassistant/components/api/__init__.py, — снабжает свой метод post декоратором @require_admin. Этот декоратор проверяет пользователя, стоящего за токеном; если это не администратор, он выбрасывает Unauthorized, который HTTP-слой Home Assistant превращает в 401 Unauthorized. В документации REST API эта точка тоже помечена как «Admin».

Она не единственная. REST API делится примерно так:

Зачем же приложению вообще точка шаблонов? Потому что часть информации отсутствует в простых точках REST. Самый явный случай — зоны: /api/states возвращает каждую сущность с её состоянием и атрибутами, но не зону, к которой она относится, а точки, которая перечисляла бы зоны, в REST API нет. Шаблон может их запросить: area_id(entity_id) и area_name(...) возвращают зону, которую Home Assistant определяет для каждой сущности — по собственной настройке сущности или по её устройству. Поэтому приложение, которое хочет показывать ваш дом по комнатам, как это делают панели Home Assistant, отрисовывает шаблон, а для этого нужен администратор.

Стоит ли давать приложению права администратора?

Собственные рекомендации по безопасности Home Assistant советуют давать права администратора только тем учётным записям, которым они нужны. Приложение, которому нужен /api/template, — как раз такой случай, и разумных вариантов два:

• Создать токен под своим пользователем-администратором. Самый простой вариант. Токен будет в вашем профиле под своим именем, и его удаление отзывает доступ только у этого приложения.
• Создать для приложения отдельного пользователя-администратора в разделе Настройки › Люди, один раз войти под ним и создать токен там. Сведения о последнем использовании будут отделены от ваших, а позже можно будет отключить этого пользователя целиком. Держите его активным, пока приложение им пользуется: токены деактивированного пользователя перестают работать. Не включайте для него Local access only (только локальный доступ), если приложение подключается и из-за пределов дома, — причина описана ниже, в разделе про 401.

В любом случае токен заслуживает той же осторожности, что и пароль: токен администратора может в Home Assistant всё, что можете вы.

«Работает, но ничего не показывает»: 401 на /api/template

Когда приложение успешно подключается, но всё равно ничего не показывает, причина почти всегда в токене пользователя, который не является администратором. Проверка подключения проходит, потому что большинство приложений проверяют GET /api/, а эта точка принимает любой действительный токен. Состояния тоже читаются. Не проходит только запрос шаблона — с ошибкой 401, и приложению, которое строит список устройств по этому шаблону, нечего показать.

Последовательность глазами приложения:

1. GET /api/ с токеном: 200, {"message": "API running."}. Приложение сообщает «подключено».
2. GET /api/states/...: 200. Состояния на месте.
3. POST /api/template, чтобы сопоставить сущности с зонами: 401. Нет зон — нет комнат — пустой экран.

Сбивает с толку то, что больше ничего не выглядит неправильным. Адрес верный, токен действителен, Home Assistant работает. Даже действия могут работать: POST /api/services/... открыт для обычных пользователей, так что свет из приложения с тем же токеном по-прежнему переключается.

Что показывает Home Assistant

Home Assistant считает каждый отправленный 401 неудачной попыткой входа, в том числе тот, что возник из-за проверки администратора. В его журнал попадает предупреждение, начинающееся со слов «Login attempt or request with invalid authentication from …», с адресом, откуда пришёл запрос (дома это обычно ваш телефон или сервер), а веб-интерфейс показывает уведомление Login attempt failed (неудачная попытка входа). Если вы включили блокировку IP с ограничением числа попыток входа, достаточное количество таких 401 заблокирует этот адрес: с этого момента он получает 403 Forbidden на всё, пока вы не удалите его из ip_bans.yaml и не перезапустите Home Assistant.

Так что если вы видите повторяющиеся уведомления о неудачной попытке входа, указывающие на ваш собственный телефон, одно из объяснений — помимо удалённого токена — приложение с токеном обычного пользователя, которое обращается к точке только для администраторов.

Как AmazHA это распознаёт и о чём сообщает

AmazHA, которое читает ваши зоны через /api/template, специально проверяет этот случай, чтобы не оставлять вас с пустыми часами:

• Когда вы нажимаете «Подключиться», телефон сначала проверяет адрес через GET /api/, затем отправляет на /api/template один простейший шаблон — {{ 1 }}. Если этот шаблон отклонён с 401, 403 или 400, токен помечается как токен не администратора. Тогда экран Home Assistant показывает Подключено ✓ с янтарной строкой под ним: «Подключено, но у этого токена нет прав администратора, поэтому часы не могут загрузить ваши сущности. Создайте долгоживущий токен у пользователя Home Assistant с ролью Administrator и вставьте его выше.»
• На часах, когда комнаты не загружаются, потому что шаблон зон отклонён, главный экран показывает баннер Нужен админ-токен · «У токена нет прав администратора — используйте админ-пользователя Home Assistant», а не общий «Офлайн».
• В отчёте для поддержки, который можно отправить из настроек AmazHA, строка «HA token» сообщает, распознан ли токен как токен администратора, — никогда не включая сам токен.

Исправление во всех случаях одно: создайте новый долгосрочный токен, войдя как администратор, вставьте его и снова нажмите Подключиться. Это показано на видео в шаге 5 урока «Если что-то не так».

Как проверить, что пользователь — администратор

Откройте Настройки › Люди, затем вкладку Пользователи. В столбце Группа у администратора указано Администраторы; если открыть пользователя, видно переключатель Администратор с пояснением, что администраторы могут управлять пользователями, устройствами, автоматизациями и панелями.

Есть проверка быстрее: если в боковой панели учётной записи, под которой вы вошли, вообще нет пункта Настройки, этот пользователь не администратор. Home Assistant регистрирует свою панель настроек только для администраторов, поэтому обычные пользователи её не видят. В таком случае выйдите, войдите как администратор и создайте токен там.

Проверьте сами с помощью curl

Любой токен можно проверить за минуту с компьютера в той же сети двумя командами curl: одной к /api/, которую проходит любой действительный токен, и одной к /api/template, которую проходит только токен администратора. В примерах адрес Home Assistant — 192.168.1.50:8123; замените его своим. Команды работают как есть в терминале macOS или Linux.

Чтобы токен не попал в историю оболочки, сначала прочитайте его в переменную. Вставьте токен, когда команда будет ждать ввода, и нажмите Enter:

read -rs HA_TOKEN

Проверка 1: действителен ли токен?

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

Действительный токен получает в ответ {"message":"API running."} и HTTP 200. Обратите внимание на косую черту в конце: точка — /api/, а не /api.

Проверка 2: принадлежит ли токен администратору?

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

Токен администратора получает отрисованный шаблон, 1, и HTTP 200. Токен обычного пользователя получает HTTP 401.

Как читать оба результата вместе:

Две оговорки. Во-первых, так вы проверяете токен со своего компьютера; приложение на телефоне может добираться до Home Assistant другим путём, особенно вне дома. Во-вторых, пройденная проверка 1 сама по себе мало что доказывает для приложений, которым нужны зоны: именно её проходит токен обычного пользователя.

401 из-за «Local access only»

Пользователь с включённым Local access only может входить только из вашей локальной сети, и Home Assistant применяет то же правило к его токенам. Запрос с адреса за пределами вашей сети или пришедший через Home Assistant Cloud отклоняется с ошибкой 401, хотя дома тот же токен работает прекрасно. Если приложение работает в вашем Wi-Fi и падает с 401 вне дома, откройте пользователя в разделе Настройки › Люди и посмотрите на этот переключатель, прежде чем подозревать удалённый адрес. Об удалённом адресе как таковом — в статье Home Assistant на часах вне дома.

Проблемы со вставкой

Токен, который выглядит правильно, всё равно может оказаться неверным, потому что вставленное не всегда совпадает с тем, что выдал Home Assistant. Home Assistant сравнивает токен посимвольно, так что один лишний или недостающий символ — это недействительный токен и 401. Обычные виновники:

Лекарство для всех одно: скопируйте токен заново кнопкой копирования в окне и вставьте напрямую. Если окно уже закрыто, токен потерян; создайте новый и удалите старую запись.

Что AmazHA очищает, а что отклоняет

AmazHA само справляется с исправимыми случаями — и когда вы сохраняете токен, и ещё раз, когда телефон читает его для запроса:

• Удаляются: пробелы, переносы строк, символы нулевой ширины, неразрывные пробелы, метки порядка байтов, мягкие переносы и метки направления текста — в любом месте токена. Ни один из них не может входить в токен Home Assistant, который состоит из букв, цифр, -, _ и точек.
• Обрезаются по краям: прямые и типографские кавычки, обратные апострофы и кавычки-ёлочки.
• Убирается в начале: вставленный Bearer (в любом регистре), потому что AmazHA добавляет это слово само.

Чего очистка исправить не может — это видимый символ, которого нет ни в одном токене, обычно … из обрезанной копии. AmazHA не гадает: такой токен оно не отправляет вовсе, поэтому ни один запрос не доходит до Home Assistant и неудачный вход не засчитывается. Экран Home Assistant в настройках показывает Недействительный токен с пояснением: «Токен содержит символ, которого не может быть в токене Home Assistant, — обычно это обрезанная копия (…). Скопируйте весь токен заново из профиля Home Assistant › Безопасность и вставьте его выше.» Часы показывают Проверьте токен · «В нём недопустимый символ — вставьте его заново». Это шаг 6 урока «Если что-то не так».

Берегите его

Относитесь к каждому долгосрочному токену как к паролю, который не истекает 10 лет: один токен на приложение, имя, по которому понятно, какое это приложение, и удаление в тот день, когда вы перестаёте им пользоваться. Конкретно:

• Один токен на приложение или устройство. Если дать один токен трём программам, нельзя отозвать его у одной, не сломав две другие, и нельзя понять, какая из них обращается к серверу.
• Называйте его по приложению. «AmazHA», «Скрипт резервного копирования», «Настенный планшет». Позже в списке вы увидите только имя; сам токен больше не показывается.
• Время от времени просматривайте список. У каждой записи указано, когда она создана, а после использования — когда и откуда её использовали в последний раз. Токен, которым никто не пользовался месяцами, — кандидат на удаление.
• Отзывайте удалением. На вкладке Безопасность удалите токен по имени. Приложение, которое им пользовалось, получит 401 при следующем запросе; больше ничего не затрагивается.
• Если токен мог утечь, удалите его и создайте новый. Удаление — единственный способ отозвать отдельный токен; замена вставляется в приложение за минуту.
• Никогда не вставляйте токен в обращение в поддержку, сообщение на форуме или скриншот. Диагностике хорошего приложения он никогда не нужен.

Удаление всех токенов обновления на той же вкладке завершает сеансы ваших устройств, но оставляет текущий сеанс и ваши долгосрочные токены, как и говорит окно подтверждения Home Assistant. Долгосрочные токены отзываются по одному.

В AmazHA

AmazHA нужен ровно один долгосрочный токен от администратора, который вводится один раз в настройках AmazHA внутри приложения Zepp; этот токен подходит и для локального, и для удалённого адреса и остаётся на вашем телефоне. Поля подключения доступны после разблокировки полной версии (разовая разблокировка, без подписки: см. Разблокировка полной версии). Дальше:

1. Создайте токен под администратором, как описано выше (шаги 1–3 урока «Подключение Home Assistant»).
2. В приложении Zepp перейдите в Профиль › ваши часы › Приложения › AmazHA › Настройки и нажмите Home Assistant (шаг 4).
3. Введите домашний адрес в поле Локальный URL (LAN), например http://192.168.1.50:8123, и, если хотите, чтобы часы работали и вне дома, внешний адрес — в поле Удалённый URL. Любое из полей можно оставить пустым.
4. Вставьте токен в поле Долгосрочный токен доступа (шаг 7).
5. Нажмите Подключиться. Если заданы оба адреса, результат показывает каждый — LAN и Удалённый; с одним адресом будет Подключено ✓. Если токен не администраторский, под результатом появится описанная выше янтарная строка.

Один токен, два адреса

Второй токен для удалённого адреса не нужен. Токен принадлежит пользователю, а не адресу: он действителен, приходит ли запрос в Home Assistant через ваш Wi-Fi или извне. Дома AmazHA использует локальный адрес; удалённый — только когда телефон не дома. Единственное исключение — описанный выше пользователь с Local access only, чей токен извне отклоняется намеренно.

Куда попадает токен, а куда — нет

Часы никогда не общаются с Home Assistant напрямую. Это делает ваш телефон через приложение Zepp, и токен хранится там, на телефоне. Он отправляется только на ваш сервер Home Assistant — в заголовке Authorization собственных запросов телефона; на часы он никогда не отправляется — они получают по Bluetooth-связи с телефоном только то, что показывают. У AmazHA нет собственного сервера, через который проходил бы токен, и отчёт для поддержки никогда его не содержит.

Что телефон делает с токеном, запрос за запросом:

Последняя строка — функция датчиков часов, которая отправляет пульс, шаги, заряд батареи и многое другое с ваших Amazfit в Home Assistant как устройство интеграции Mobile App: об этом — статья Как отправить данные Amazfit в Home Assistant.

Когда AmazHA сообщает что-то о токене

Короткий код под Офлайн нужен для поддержки: если будете писать, фото часов точно покажет, что не сработало. Обо всех остальных сообщениях, которые могут показать часы, — в уроке «Если что-то не так».