API-токены

API-токен — ключ, которым программы работают с Notifly от имени вашего аккаунта. Один и тот же токен предъявляют Go и Python SDK, CLI и MCP-сервер для AI-ассистентов. Префикс — M, выпускается в админке на странице API-токены.

Какой токен для чего

Токен	Префикс	Для чего
API-токен	M	Всё на уровне аккаунта: каналы, heartbeat-ы, мониторы, сканы, история, администрирование сообщений. Со скоупом по каналам и тегам, с уровнем доступа и сроком действия
Токен канала	A	Только отправка в один канал: POST /message, POST /ask. Им пользуются notifly push, GitHub Action и любой скрипт, который «просто шлёт уведомления»
Токен устройства	C	Сессия приложения или браузера. Сервер принимает его на тех же маршрутах, что и API-токен, но это не ключ для интеграций — см. ниже
Токен доступа	S	Делегированный доступ к чужому каналу: чтение и, при праве send, отправка. Выдаётся владельцем канала

Токен устройства — не API-ключ

Токен C… выдаётся при входе и живёт как сессия: он занимает слот в лимите устройств тарифа, при входе с нового устройства на пределе лимита самое старое устройство суспендится, а смена пароля ротирует токены всех остальных устройств. Скрипт, настроенный на такой токен, однажды получит 401 без всякой связи со своей работой. Для интеграций берите API-токен.

Как выпустить

1. Админка → Управление → API-токены → Выпустить API-токен.
2. Задайте название (оно видно только вам), уровень доступа, каналы и, если нужно, срок действия.
3. Скопируйте значение из диалога — оно показывается один раз.

Осторожно

В базе токен хранится только хешем, поэтому полное значение существует ровно в ответе на выпуск и на перевыпуск. В списке остаётся короткая метка вида M…ab3d — по ней вы узнаёте токен, но подставить её в конфиг нельзя. Потеряли значение — перевыпустите токен.

Права и скоуп

Уровень доступа:

• read — только чтение (GET, списки, поиск). Любая изменяющая ручка отвечает 403.
• write — полный CRUD в границах скоупа.

Скоуп по каналам задаётся двумя способами, они складываются:

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

Пустой скоуп (ни каналов, ни тегов) означает «все каналы аккаунта».

Канал, созданный самим токеном, всегда попадает в его скоуп: у токена без ограничений он виден автоматически, а ограниченному токену сервер дописывает id нового канала в список. Иначе notifly create-app и CreateChannel из SDK создавали бы канал, которого создатель тут же не видит.

Минимальный скоуп для агента

Токену, который вы отдаёте AI-ассистенту, разумно выдать read, ограничить теги и поставить срок действия. Тогда даже утёкший из логов или истории чата токен ничего не сломает и сам протухнет.

Срок действия

Необязательное поле: после указанного момента токен отклоняется на аутентификации как невалидный (401), строка при этом остаётся — её видно в списке с пометкой «истёк». Продлить срок можно редактированием токена, перевыпуск тоже сохраняет прежний срок.

Перевыпуск и удаление

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

Удалить — отключить токен насовсем. Кеша у API-токенов нет, поэтому и удаление, и перевыпуск, и сужение скоупа действуют сразу на всех серверах.

Все API-токены аккаунта удаляются автоматически при сбросе пароля по ссылке из письма — это сценарий восстановления после угона, — а также когда пароль пользователю меняет администратор. Обычная смена пароля из настроек их не трогает (подробнее — в Безопасности аккаунта).

Куда подставить

Go SDK

client := notifly.New(notifly.WithAPIToken("M<api-token>"))
monitors, err := client.ListMonitors(ctx)

Python SDK

from notifly import Notifly

nf = Notifly("M<api-token>")
nf.list_channels()

Подробнее про оба SDK — на странице Go и Python SDK.

CLI — поле apiToken в cli.json или переменная окружения; нужен командам create-app и list (см. CLI-клиент):

export NOTIFLY_API_TOKEN=M<api-token>
notifly list -n 10

MCP-сервер — переменная NOTIFLY_API_TOKEN в конфиге вашего AI-клиента (см. MCP-сервер).

REST напрямую — заголовок X-Notifly-Key:

curl -H "X-Notifly-Key: M<api-token>" https://api.notifly.ru/application

Чего API-токеном сделать нельзя

Потолок привилегий задан намеренно: утёкший ключ не должен превращаться в полный доступ к аккаунту.

• Управлять устройствами — /client* закрыты.
• Управлять API-токенами — токен не выпускает, не правит, не ротирует и не удаляет ни себя, ни соседей.
• Менять пароль, настраивать 2FA и подтверждать чувствительные действия — для этого нужен живой токен устройства и sudo-окно.
• Быть администратором — admin-ручки отвечают 403 независимо от того, чей это аккаунт.
• Подключаться к WebSocket — /ws принимает токен устройства (C…) и токен канала с правом чтения (A…, S…); см. WebSocket-протокол.
• Читать подписки устройства — у API-токена нет устройства, такие ручки отвечают 401.

REST

Управление токенами доступно только с токеном устройства — API-токен к этим ручкам не допускается.

Метод и путь	Описание
GET /api-token	Список токенов. Поле token — метка M…ab3d, не секрет
POST /api-token	Выпустить. Единственный ответ с полным значением
PUT /api-token/{id}	Изменить название, доступ, скоуп, срок
POST /api-token/{id}/rotate	Перевыпустить: новое значение, прежние настройки
DELETE /api-token/{id}	Удалить

Поля тела: name, access (read/write), appIds (массив id каналов), appTags (массив тегов), expiresAt (RFC3339). При обновлении отсутствующие appTags и expiresAt означают «не менять», пустой массив appTags — «очистить».