Channel delegation (Sharing)

Delegation (sharing) is a way to give another person access to one of your channels without letting them into the rest of the account. A colleague will get either the right to only read messages from that channel, or to read and send new ones — but will not be able to see your other channels, change settings, or manage clients and tokens.

Useful when:

• you need to show the team only the Prod-алёрты channel without exposing the whole project;
• a CI bot only needs to send to one channel (the send permission) and nothing else;
• the on-call person should see incoming notifications for a specific service (view);
• you want to grant access temporarily — a delegation can be easily revoked without touching the channel’s tokens.

Technically, each delegation is a separate Share token with the S prefix, bound to a channel. The channel owner issues the token, optionally specifying the recipient’s email and the permission level. The recipient uses the token like a regular notifly token (see below How the recipient uses the access).

Access levels (permission)

permission	What is allowed
view	See the channel in the list and read its messages (GET /message).
send	Same as view, plus sending messages (POST /message).

send includes view. Any mutations of the channel itself, clients, tokens, as well as deleting messages using a Share token are forbidden (response 403).

Message sent as the owner

When sending with a Share token that has send permission, the identity is substituted with the channel owner: the message appears as if it were sent by the owner. The recipient does not gain access to the rest of the account — only to this channel.

Invitation statuses (status)

A delegation to a specific email is first created as an invitation which the recipient can accept or decline:

status	What it means
pending	The invitation has been issued; the recipient has not yet reacted.
accepted	The recipient accepted — the channel has appeared in their list.
declined	The recipient declined the invitation.

Only a pending invitation can be accepted (POST /share/:id/accept); attempting to accept/decline an already processed one will return 400 share is not pending.

How to share a channel

The request is made by the channel owner (or a delegated user — see Re-sharing) using a client token or MCP code with write permission.

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": "Дежурному на эту неделю"
         }'

Request body fields (ChannelShareParams):

Field	Type	Required	Description
permission	string	yes	view or send. Any other value → 400.
recipientEmail	string	no	Recipient’s email. If empty — becomes an “open share” (see below).
note	string	no	Arbitrary comment for yourself (e.g. “for CI”, “for colleague X”).

Response — the created ChannelShare object:

{
  "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-алёрты"
}

The token field (prefix S) is the Share token. Give it to the recipient by any channel, or rely on them finding the invitation via incoming.

Open share (without email)

If recipientEmail is left empty, the delegation becomes an open share — a link/token that anyone who has it can use. In this case the recipient joins via POST /share/join, and a personal copy of the delegation (with its own Share token) is created for them, leaving the original untouched. This is convenient for invitations like “forward the link to the team”.

Open share = link for everyone

An open share is not tied to a specific address: anyone who gets the token will be able to join. Do not publish it where it could leak.

How the recipient uses the access

After the delegation is accepted (accepted), the channel appears in the recipient’s normal list (GET /application). Then the Share token is used like any notifly token:

# Чтение сообщений канала (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=Готово'

A Share token grants access strictly to a single channel. Attempts to call mutating endpoints (create/modify a channel, delete a message, manage tokens) will return 403 share tokens cannot perform this action.

Incoming invitations (for the recipient)

The recipient sees delegations issued to their email via GET /share/incoming. Both unaccepted (pending) and accepted (accepted) are returned — except for invitations to channels the recipient already owns, and pending duplicates with the same permissions as an already accepted delegation.

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

Accept or decline

# Accept — the channel will appear in the recipient's list
curl -X POST "$NOTIFLY_URL/share/1007/accept" -H "X-Notifly-Key: <client-token>"

# Decline
curl -X POST "$NOTIFLY_URL/share/1007/decline" -H "X-Notifly-Key: <client-token>"

Only the user whose email matches the delegation’s recipientEmail can accept/decline; otherwise — 404. Only a pending invitation can be processed.

Joining by token

If the recipient was given the Share token directly (for example, an open share or simply the S... string), they join with a single call:

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

Behavior depends on the type of delegation:

• Named (with recipientEmail): the token joins only if the user’s email matches the delegation’s address (otherwise 403 this share is not for your email). The status is automatically changed to accepted.
• Open share (without email): a personal copy of the delegation is created for the joiner with status accepted. If they already have a delegation for this channel, it is upgraded to send if necessary and set to accepted.

Invalid token → 404 invalid share token.

Managing issued delegations (for the owner)

List of delegations for a specific channel (only those you created are shown; the channel owner also sees legacy delegations without a creator):

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

Change the permission level, email, or note — PUT /share/:id (channel owner only):

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"}'

Revoke a delegation — DELETE /share/:id. It can be deleted by its creator or the channel owner (for legacy delegations without a creator). After deletion, the token immediately stops working and the channel disappears from the recipient’s list.

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

To avoid typing emails manually, the sharing form can suggest addresses you’ve already shared with — GET /share/recipients returns a list of distinct emails from newest to oldest:

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

Re-sharing (delegating further)

A delegated user can, in turn, share the channel further — but not above their own permission level. If you only have view, attempting to grant send will return:

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

The channel owner is always considered to have maximum access (send). Each user in the GET /application/:id/share list sees only their own delegations (the created_by field), so re-sharing does not expose other users’ delegations for the same channel.

REST API

Method and path	Authorization	Purpose
GET /application/:id/share	client-token	list of channel delegations (only your own)
POST /application/:id/share	client-token (write)	create a delegation (issue a Share token)
PUT /share/:id	client-token (write)	change permission / email / note (channel owner)
DELETE /share/:id	client-token (write)	revoke a delegation
GET /share/incoming	client-token	incoming invitations to the user’s email
GET /share/recipients	client-token	email addresses you’ve already shared with (for suggestions)
POST /share/:id/accept	client-token	accept a pending invitation
POST /share/:id/decline	client-token	decline a pending invitation
POST /share/join	client-token	join a channel by Share token

Where this is in the admin UI

Sharing channels and accepting invitations is more convenient via the UI at app.notifly.ru — the REST endpoints are for automation (for example, issuing a send delegation to a CI bot via a script).