Делегирование каналов (Sharing)

Делегирование (sharing) — это способ дать другому человеку доступ к одному вашему каналу, не пуская его в остальной аккаунт. Коллега получит право либо только читать сообщения этого канала, либо читать и отправлять в него новые — но не сможет ни видеть другие ваши каналы, ни менять настройки, ни управлять клиентами и токенами.

Удобно, когда:

• нужно показать команде только канал Prod-алёрты, не открывая весь проект;
• CI-боту нужно лишь слать в один канал (право send) и больше ничего;
• дежурный должен видеть входящие уведомления конкретного сервиса (view);
• хочется передать доступ временно — делегацию легко отозвать, не трогая токены самого канала.

Технически каждая делегация — это отдельный Share-токен с префиксом S, привязанный к каналу. Владелец канала выпускает токен, опционально указывает email получателя и уровень доступа. Получатель пользуется токеном как обычным notifly-токеном (см. ниже Как получателю пользоваться доступом).

Уровни доступа (permission)

permission	Что разрешено
view	Видеть сам канал в списке и читать его сообщения (GET /message).
send	То же, что view, плюс отправлять сообщения (POST /message).

send включает в себя view. Любые мутации самого канала, клиентов, токенов, а также удаление сообщений по Share-токену запрещены (ответ 403).

Сообщение от имени владельца

При отправке по Share-токену с правом send identity подменяется на владельца канала: сообщение выглядит так, будто его отправил владелец. Получатель не получает доступа к остальному аккаунту — только к этому каналу.

Статусы приглашения (status)

Делегация на конкретный email сначала создаётся в статусе приглашения, которое получатель может принять или отклонить:

status	Что значит
pending	Приглашение выдано, получатель ещё не отреагировал.
accepted	Получатель принял — канал появился у него в списке.
declined	Получатель отклонил приглашение.

Принять можно только pending-приглашение (POST /share/:id/accept); попытка принять/отклонить уже обработанное вернёт 400 share is not pending.

Как поделиться каналом

Запрос делает владелец канала (или делегированный пользователь — см. Ре-шеринг) клиент-токеном или MCP-кодом с правом записи.

curl -X POST "$NOTIFLY_URL/application/42/share" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
           "recipientEmail": "colleague@example.com",
           "permission": "view",
           "note": "Дежурному на эту неделю"
         }'

Поля тела (ChannelShareParams):

Поле	Тип	Обязательно	Описание
permission	string	да	view или send. Другое значение → 400.
recipientEmail	string	нет	Email получателя. Если пусто — получается «open share» (см. ниже).
note	string	нет	Произвольный комментарий для себя («для CI», «коллеге Х»).

Ответ — созданный объект ChannelShare:

{
  "id": 1007,
  "token": "S9f3k...",
  "appid": 42,
  "recipientEmail": "colleague@example.com",
  "permission": "view",
  "status": "pending",
  "note": "Дежурному на эту неделю",
  "created": "2026-06-23T10:00:00Z",
  "lastUsed": null,
  "appName": "Prod-алёрты"
}

Поле token (префикс S) — это и есть Share-токен. Передайте его получателю любым каналом, либо рассчитывайте на то, что он сам найдёт приглашение через входящие.

Open share (без email)

Если оставить recipientEmail пустым, делегация становится open share — ссылкой/токеном, которым может воспользоваться кто угодно, у кого он есть. В этом случае получатель присоединяется через POST /share/join, и для него создаётся персональная копия делегации (со своим Share-токеном), не затрагивая оригинал. Это удобно для приглашений вида «перешлите ссылку команде».

Open share = ссылка для всех

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

Как получателю пользоваться доступом

После того как делегация принята (accepted), канал появляется в обычном списке получателя (GET /application). Дальше Share-токен используется как любой notifly-токен:

# Чтение сообщений канала (view и send)
curl "$NOTIFLY_URL/message" -H "X-Notifly-Key: S9f3k..."

# Отправка в канал (только send)
curl -X POST "$NOTIFLY_URL/message" \
     -H "X-Notifly-Key: S9f3k..." \
     -d 'title=Деплой&message=Готово'

Share-токен даёт доступ строго к одному каналу. Попытка вызвать мутирующие эндпоинты (создать/изменить канал, удалить сообщение, управлять токенами) вернёт 403 share tokens cannot perform this action.

Входящие приглашения (получателю)

Получатель видит выданные на его email делегации через GET /share/incoming. Возвращаются как ещё не принятые (pending), так и принятые (accepted) — кроме приглашений на каналы, которыми получатель уже владеет, и pending-дубликатов с теми же правами, что у уже принятой делегации.

curl "$NOTIFLY_URL/share/incoming" -H "X-Notifly-Key: <client-token>"

Принять или отклонить

# Принять — канал появится в списке получателя
curl -X POST "$NOTIFLY_URL/share/1007/accept" -H "X-Notifly-Key: <client-token>"

# Отклонить
curl -X POST "$NOTIFLY_URL/share/1007/decline" -H "X-Notifly-Key: <client-token>"

Принять/отклонить может только пользователь, чей email совпадает с recipientEmail делегации; иначе — 404. Обработать можно только pending-приглашение.

Присоединение по токену

Если получателю передали Share-токен напрямую (например, open share или просто строку S...), он присоединяется одним вызовом:

curl -X POST "$NOTIFLY_URL/share/join" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{"token": "S9f3k..."}'

Поведение зависит от типа делегации:

• Именная (с recipientEmail): токен присоединяет, только если email пользователя совпадает с адресом делегации (иначе 403 this share is not for your email). Статус автоматически переводится в accepted.
• Open share (без email): создаётся персональная копия делегации для присоединившегося со статусом accepted. Если у него уже есть делегация на этот канал, она при необходимости повышается до send и переводится в accepted.

Неверный токен → 404 invalid share token.

Управление выданными делегациями (владельцу)

Список делегаций конкретного канала (показываются только созданные вами; владельцу канала также видны legacy-делегации без автора):

curl "$NOTIFLY_URL/application/42/share" -H "X-Notifly-Key: <client-token>"

Изменить уровень доступа, email или комментарий — PUT /share/:id (только владелец канала):

curl -X PUT "$NOTIFLY_URL/share/1007" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{"permission": "send", "recipientEmail": "colleague@example.com"}'

Отозвать делегацию — DELETE /share/:id. Удалить может тот, кто её создал, либо владелец канала (для legacy-делегаций без автора). После удаления токен немедленно перестаёт работать, и канал исчезает из списка получателя.

curl -X DELETE "$NOTIFLY_URL/share/1007" -H "X-Notifly-Key: <client-token>"

Чтобы не вводить email вручную, форма шеринга может подсказать адреса, с кем вы уже делились, — GET /share/recipients возвращает список distinct-email от самых свежих к старым:

curl "$NOTIFLY_URL/share/recipients" -H "X-Notifly-Key: <client-token>"

Ре-шеринг (делегирование дальше)

Делегированный пользователь может, в свою очередь, поделиться каналом дальше — но не выше собственного уровня доступа. Если у вас есть только view, попытка выдать send вернёт:

403 cannot grant 'send' permission — you only have 'view' access

Владелец канала всегда считается имеющим максимальный доступ (send). Каждый пользователь в списке GET /application/:id/share видит только свои делегации (поле created_by), поэтому ре-шеринг не раскрывает чужие делегации того же канала.

REST API

Метод и путь	Авторизация	Назначение
GET /application/:id/share	client-token	список делегаций канала (только свои)
POST /application/:id/share	client-token (write)	создать делегацию (выдать Share-токен)
PUT /share/:id	client-token (write)	изменить permission / email / note (владелец канала)
DELETE /share/:id	client-token (write)	отозвать делегацию
GET /share/incoming	client-token	входящие приглашения на email пользователя
GET /share/recipients	client-token	email-адреса, с кем вы уже делились (для подсказок)
POST /share/:id/accept	client-token	принять pending-приглашение
POST /share/:id/decline	client-token	отклонить pending-приглашение
POST /share/join	client-token	присоединиться к каналу по Share-токену

Где это в админке

Делиться каналами и принимать приглашения удобнее через UI на app.notifly.ru — REST-эндпоинты нужны для автоматизации (например, выдать send-делегацию CI-боту скриптом).