Inbox, realtime, and Web Push
Your frontend uses a short-lived user token, issued by your authenticated backend. The token identifies one application, account, and recipient.
Inbox
| Operation | Endpoint |
|---|---|
| Read inbox | GET /v1/user/inbox |
| Read unread count | GET /v1/user/inbox/unread-count |
| Mark one item read | POST /v1/user/inbox/{id}/read |
| Mark all items read | POST /v1/user/inbox/read-all |
Inbox responses contain data and a next_before cursor. Pass that timestamp as before when requesting the next page. You may request unread items using status=unread.
Notify derives recipient identity from the token. Sending another recipient header does not switch a user token's identity.
Realtime with SSE
GET /v1/user/realtime/events opens a Server-Sent Events stream. Use a streaming fetch or an SSE client that supports an Authorization header. Native browser EventSource does not provide a custom-header option.
Reconnect with backoff, refresh the token before expiration, and close connections when the user signs out or switches account. Treat events as a prompt to refresh inbox state rather than a replacement for persisted inbox reads.
Web Push
- Read the public VAPID key from
GET /v1/user/push/config. - Register your application's service worker.
- Request notification permission after an intentional user action.
- Create a browser
PushSubscription. - Register it with
POST /v1/user/push/subscriptions, following the API schema. - Use
DELETE /v1/user/push/subscriptions/{id}to remove a subscription when appropriate.
The platform must configure VAPID before push is available. Your service worker handles incoming pushes and notification clicks. Notify does not automatically install a service worker or build your notification UI.
Distinct experiences
An in-app notification is persisted in the inbox. SSE updates connected pages. Web Push delivers a browser notification via a service worker. Enabling one does not automatically implement the other two; select the channels and frontend features your product needs.