The ActivityPub specification defines a server-to-server federation protocol but does not specify how a client application (e.g. a Web front-end or mobile app) receives real-time notifications from an ActivityPub server. This FEP proposes a straightforward, standards-aligned approach using HTTP/1.1 Server-Sent Events.
Goals:
This FEP specifies a lightweight, cookie-authenticated Server-Sent Events (SSE) streaming API that ActivityPub server implementations can expose to their authenticated clients. The API provides:
The design intentionally separates authentication (handled by the server’s existing mechanism, e.g. OAuth 2.0, session cookies, or HTTP Basic) from streaming authorization (a short-lived ticket stored in an HttpOnly cookie), so that the SSE connection never carries user credentials.
This proposal addresses two issues related to SSE event streaming in an ActivityPub context.
EventSource API does not allow sending HTTP headers when opening an SSE event stream, some proposals recommend sending credentials in the streaming URL. However, this is not desirable because of the risk that the credentials may be exposed in logs of servers (including proxy server outside the control of the the AP server operator).| Term | Definition |
|---|---|
| Actor | A standard ActivityPub actor |
| Principal | The authenticated identity (URI of the Actor) making a request. |
| Ticket | A short-lived, randomly-generated opaque token that authorizes one SSE stream connection. |
| Topic | An opaque string naming a channel of events (e.g. notifications, inbox, timeline:home). |
| SSE Session | The lifecycle from ticket issuance through stream connection to ticket revocation or expiry. |
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in RFC 2119.
The streaming control endpoint is exposed using the ActivityPub Actor endpoints property using the streamingControl endpoint property.
{
"@context": [
"https://w3id.org/fep/3ab2",
"https://www.w3.org/ns/activitystreams"
],
"type": "Person",
"id": "https://server.example/actor/1",
...
"endpoints": [
"streamingControl": "https://server.example/streaming/control"
]
}
Topic represented as multiple text segments separated by the “/” character.
For subscriptions, topics MAY contain wildcards if the server supports them. The standard [MQTT wildcards][MQTT Wildcards] are used for this purpose. A server can advertise wildcard support in the Create Session response via the wildcard_support field.
| Wildcard | Description | Example |
|---|---|---|
| + | Matches a single topic segment | foo/+/baz |
| # | Matches zero or more segments at the end of the pattern | foo/# |
When publishing, the topic MUST use URL escaping for any wildcard characters in the topic. Subscribers MUST also escape non-wildcard ‘+’ and ‘#’ characters in topic subscriptions.
For ActivityPub entities, topics will correspond to ActivityPub HTTP/HTTPS URIs. To construct a topic from a URI, the following algorithm is used.
Topic wildcard characters in topic segments MUST be URL-escaped.
Examples
| URL | Topic |
|---|---|
https://server.example/note/1 |
server.example/note/1 |
https://server.example:1000/actor#xyz |
server.example:1000/actor/xyz |
https://server.example:1000/actor+123#xyz |
server.example:1000/actor%2B123/xyz |
POST {streamingControl}Requires: authenticated Principal.
The server:
Set-Cookie response header carrying the ticket value with the configured path, SameSite, Secure, and HttpOnly attributes.201 Created with a JSON body.Server Response body:
| Field | Type | Description |
|---|---|---|
subscriptions_url |
string | Required. Absolute URL of the subscriptions endpoint. Clients MUST use this value for all subscription management requests in this session. |
stream_url |
string | Required. Absolute URL of the SSE stream endpoint. Clients MUST use this value to open the event stream. |
expires_at |
string | ISO 8601 UTC timestamp of ticket expiry |
wildcard_support |
bool | Indicates whether the server supports topic wildcards or not. Defaults is true if not provided. |
Servers MUST include subscriptions_url and stream_url in every successful 201 Created response to this endpoint. Clients MUST treat these URLs as opaque and MUST NOT attempt to derive or construct them from the SSE prefix or any other path convention.
Example
{
"subscriptions_url": "https://server.example/sse/control/subscriptions",
"stream_url": "https://server.example/sse/stream",
"expires_at": "2001-03-10T12:05:00Z",
"wildcard_support": true
}
Cookie attributes (RECOMMENDED defaults):
| Attribute | Recommended value |
|---|---|
Path |
Scoped to the implementation’s streaming API path |
SameSite |
Lax |
Secure |
true in production |
HttpOnly |
Server MAY set to false to allow JavaScript access |
Max-Age |
Cookie expiry age |
The ticket MUST expire after a server-configured TTL. Clients MUST call POST /control again to renew before opening a new stream.
DELETE {streamingControl}Requires: authenticated Principal. The ticket cookie is read if present.
The server:
Set-Cookie header that clears the cookie (Max-Age=0).204 No Content if successfull.Client implementations SHOULD also close any active SSE connections associated with the revoked ticket.
All subscription endpoints require both:
Violating either condition MUST result in 401 Unauthorized.
GET {subscriptions_url}Response:
{
"topics": ["notifications", "timeline:home"]
}
| Field | Type | Description |
|---|---|---|
topics |
string array | The full set of subscribed topics. An empty array indicates no active subscriptions. |
POST {subscriptions_url}Request body:
{
"topics": [
"remote-server.example/note/abcd"
"server.example/note/#",
]
}
| Field | Type | Required | Description |
|---|---|---|---|
topics |
string array | yes | The topic identifiers or patterns |
Response:
{
"topics": [
"remote-server.example/note/abcd"
"server.example/note/#",
"server.example/another-topic"
]
}
| Field | Type | Description |
|---|---|---|
topics |
string array | The full set of subscribed topics. The array reflects the full set of subscriptions after the operation. Adding a topic that is already subscribed is idempotent and MUST NOT return an error. |
DELETE {subscriptions_url}?topic={topic}The topic query parameter is required. Removing a non-existent topic MUST be idempotent (no error).
Response:
204 No Content HTTP status.GET {stream_url}Requires:
The client MUST send Accept: text/event-stream.
On success the server:
Content-Type: text/event-stream).Cache-Control: no-cache and (if behind a reverse proxy) X-Accel-Buffering: no.ServerSentEvent frames for all topics the user is currently subscribed to.Only one active stream per Principal SHOULD be supported at a time; if a second stream is opened the server MAY close the first.
The ticket is single-use. The server MUST only create one stream per ticket.
Each event follows the W3C EventSource wire format:
id: <event-id>\n
event: activitypub\n
data: <JSON-object>\n
\n
| SSE field | Value |
|---|---|
id |
The id field of the payload object, or a server-generated UUID hex |
event |
activitypub (implementations MAY define additional named event types) |
data |
A JSON-serialized Activitypub entity |
Example ActivityPub Event Payload (data)
{
"@context":"https://www.w3.org/ns/activitystreams",
"id": "https://example.com/activities/abc123",
"type": "Create",
"published": "2026-03-10T11:00:00Z",
"object": { ... }
}
Servers SHOULD send periodic SSE heartbeat events (event: heartbeat) at regular intervals (RECOMMENDED: every 15–30 seconds) to prevent proxy timeouts and help clients detect dead connections. The id and data fields are optional in these messages.
DELETE /control).Secure (HTTPS only) in production.SameSite=Lax or SameSite=Strict MUST be set to mitigate CSRF.HttpOnly SHOULD be set unless the client is a first-party JavaScript application that must read the cookie.401 Unauthorized.SSE connections SHOULD be protected against cross-origin misuse via [CORS][CORS] headers restricting Origin to trusted first-party origins.
app.example -> api.example), then CORS is required and must be strict:
Access-Control-Allow-Origin must be the exact SPA origin, not *.Access-Control-Allow-Credentials: true is required if cookies are used.Vary: Origin should be set.Origin against an allowlist and reject others.The SSE stream may carry sensitive information (notifications, timeline events). Implementations MUST:
Another common technique for implementing event stream is to use Websockets. SSE has several advantages over WebSockets for streaming purposes.
Native unidirectional model: SSE is designed exactly for server→client event streams (logs, notifications, token streaming, dashboards), so you are not paying for a full‑duplex channel you don’t need.
Runs over plain HTTP: Messages are just a long‑lived HTTP response using text/event-stream, so it works naturally with existing HTTP infrastructure (proxies, load balancers, CDNs) without special ws upgrade handling.
Simpler implementation and debugging: On the server you just write to the response stream; on the client you use the EventSource API, no custom framing or libraries needed, which reduces code size and potential bugs.
Better proxy/firewall compatibility: Because it is just HTTP, SSE usually passes through corporate firewalls and middleboxes more reliably than WebSocket upgrades, which some environments still block or interfere with.
HTTP/2 friendliness: With HTTP/2 you can multiplex multiple SSE streams over a single TCP connection, leveraging the same optimizations as the rest of your HTTP traffic, whereas WebSockets use a separate protocol and do not get the same native multiplexing.
[MQTT Wildcards]: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901241 “” [CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.