Skip to main content
A web page can receive Realtime events straight from OFAuth over Server-Sent Events. Your server creates a stream URL; the page opens it:
The page sends no authorization headers or access tokens. The URL contains a scoped stream credential.
Never send an access token to a browser. Anyone who can read the page, its storage, or its network traffic could call the API as your app. The access-token APIs (/v3/access, /v3/linked-accounts, /v3/vault-plus, Realtime with Authorization: Bearer) send no CORS headers, so browsers block them.

Create a stream URL on your server

Return url only to a signed-in user who may see that linked account. An endpoint in your app, for example with Express:

Open it in the page

The TypeScript SDK provides a browser entry point that handles reconnects, cursor replay, duplicate events, and tab sharing:
Call the returned function from your view’s cleanup handler. Create a new stream with the new linkedAccountId after an account switch. The helper cancels pending reconnects and releases this tab’s lock when closed. Each event arrives as:
data is the same JSON as on the server stream. Delivery is at least once: ignore an eventId you have already handled.

Reconnects and reauth

  • Network drops: EventSource reconnects by itself with the same URL and sends the last id. OFAuth replays what you missed (the last 15 minutes, up to 1,000 events). You don’t need to do anything.
  • resync: the missed events are no longer available. Refetch the state you show, then keep listening.
  • closed with reauth: the stream URL expired (after 10 minutes), or the account is no longer shared with your app. The SDK gets a new URL from your server. If your server can’t create one (401 or 403), stop.
  • After reauth, the old URL returns 401, so EventSource stops retrying by itself.
  • closed with unavailable, or the stream drops: EventSource reconnects by itself. If OFAuth answers 503 during an outage, EventSource stops (readyState is CLOSED); the SDK retries with jittered backoff, up to 30 seconds by default.
  • closed with replaced: more than 10 streams were open for this linked account and authorization, and this one was the oldest. A new stream can replace a browser stream; if all 10 streams use server bearer authentication, it receives 429 stream_limit instead. The replaced stream’s URL now returns 409 stream_replaced, so EventSource stops by itself; don’t reconnect automatically. The SDK stops in replaced until you call stream.resume().

One stream per browser

Each open tab with its own EventSource counts as one stream. The SDK helper shares a stream by linkedAccountId using BroadcastChannel and a Web Lock. Only the leader tab requests a stream URL; followers receive events and cursors through the channel. When the leader closes its stream or tab, another tab takes over with a new URL and the last cursor it received. Tab sharing needs both APIs in a secure context. Without them, each tab opens its own stream. Close the old stream before changing accounts or signing out. Use each URL for one EventSource only: reconnecting with the same URL replaces only that URL’s previous connection.

Why a URL is safe enough here

The stream URL carries a short-lived credential, so treat the URL like a password:
  • It only opens this event stream, read-only, for one linked account. It can’t call the API.
  • It works for 10 minutes at most, and never longer than your access token.
  • OFAuth checks the account’s access on every connect and every 30 seconds while the stream is open. A new connection is refused after authorization is removed; an open stream closes when its next authorization check fails.
  • The stream sends Referrer-Policy: no-referrer, and OFAuth doesn’t log stream URLs. Don’t log them in your app either.
Your server can use the same stream with Authorization: Bearer instead of a stream URL; see Receive Realtime over Server-Sent Events.