Notification API

atreoAGENT ships with an end-to-end encrypted notification system. Apps on your server send notifications to a local API. The agent encrypts each notification to the recipient’s atreoLINK identity key and relays it to atreoLINK, which fans out to phones and browsers. atreoLINK never sees the plaintext.

How it works

1. An app on your server sends a notification to the local API on port 9876, addressing it by userId or userEmail. The request carries the bearer-token API key.
2. The agent looks up the recipient in its ACL, builds three encrypted fields (summary, optional HTML, optional plaintext), and posts them to atreoLINK.
3. atreoLINK fans out to every paired client owned by that user: iPhone, iPad, Android phones, and any paired browser. (Apple TV and Android TV don’t receive notifications; see below.)
4. The client decrypts on receipt and shows the notification.

atreoLINK only ever sees opaque ciphertext.

Components

• Local API for senders, on port 9876. Authenticated by a bearer-token API key. See the API reference.
• SMTP gateway for self-hosted apps that only support email. See Built-in SMTP server.
• End-to-end encryption to each recipient’s atreoLINK identity key. See Encryption.
• Mobile delivery via APNs (iOS) and FCM (Android), relayed through atreoLINK.
• Browser delivery via WebPush, with a per-browser layer on top of the inner end-to-end layer.

Note

The notification API binds on all interfaces so self-hosted apps running in their own Docker containers can reach it via the host’s network. Access is gated by the bearer-token API key. Keep the agent behind your home router’s NAT and don’t port-forward 9876.

What clients receive notifications

Platform	Notifications?
iPhone, iPad	Yes
Android phones, tablets	Yes
Browsers (Chrome, Firefox, Safari 16.4+)	Yes
Apple TV (tvOS)	No
Android TV / Fire TV	No

The TV builds don’t pair for notifications. There’s no Notifications tab on TV.

System notifications

The agent sends its own notifications automatically:

Event	Severity	Description
Port mapping lost	error	Router assigned the wrong port; tunnels broken.
Port mapping recovered	info	Correct port restored; tunnels resuming.

Authentication

The local API is protected by a bearer token. Apps include it in Authorization: Bearer <api-key>. The key is generated automatically on first boot and stored at <DATA_DIR>/notify_api_key (default /var/lib/atreoagent/notify_api_key).

Read the current key

From the dashboard: sign in to app.atreolink.com, open your server’s Settings tab, and look for Notification API key.

From the host:

docker exec atreoagent cat /var/lib/atreoagent/notify_api_key

Rotate the key

In the dashboard, Settings → Notification API key → Rotate key. The agent generates a new random token and atomically replaces the file.

The old key stops working the moment you rotate; there’s no grace period.

Scope

The API key is per server, not per user. Every app on the server uses the same key. The same key also doubles as the password for the built-in SMTP gateway, so apps that only speak SMTP can authenticate with it directly.

See the API reference for endpoint details.

Rate limits

Two caps apply to the notify path:

• Per server: 120 notifications per minute across all apps sending through this agent.
• Per recipient: 60 notifications per minute to any one member, counted across every server they’re linked to and every device they’ve paired.

Over-budget requests are rejected with no queueing. See Rate limits for details.

Retention

atreoLINK’s archive keeps at most the 100 most recent notifications per recipient. When a new notification arrives at the cap, the oldest is deleted.

Unpairing a server does not delete the notifications it already sent. They are detached from the (now-removed) server and stay in your inbox — still readable, markable as read, and deletable — until you remove them yourself or they rotate out under the 100-per-recipient cap. A detached notification simply loses its “from <server>” label.