API Reference

:::tip Interactive reference Browse and call every endpoint in the Notify API Explorer — live "Try it" in dev/test, read-only in prod. This page keeps the conceptual auth overview; the full endpoint contract lives in the explorer. :::

Every Notify web push route lives under /api/v1. The API base URL is configured per environment (local: http://localhost:8088), so every path below is really <<base>>/api/v1<<path>>.

This page is a lookup table for auth concepts. For the end-to-end flow, read the Integration Guide first.

note

There are two auth families. Browser lifecycle routes (subscriptions, lifecycle events) use the push-platform token. Admin / editor routes (templates, send, activity) use the editor token. See Configuration & Secrets for how each token is provisioned.

Auth at a glance

Auth type	Route groups	Required headers
Push-platform token	Group A (client-config, subscriptions, lifecycle events)	Authorization: Bearer <push-platform token>, X-Source-App: <allowed app>
Editor token	Group B (templates, send, activity)	Authorization: Bearer <editor token>
Editor token + admin	Group B writes (create / update / delete / preview)	Authorization: Bearer <editor token>, X-Admin-User: <user>
Editor token + tenant scope	Group B tenant-scoped reads	Authorization: Bearer <editor token>, X-Notify-Client-Id: <client>
Player JWT	Player notifications (list, read/unread, read-all/unread, delete)	Authorization: Bearer <player JWT> (tenant_id/user_id claims)

The push-platform token is validated against NOTIFY_API_PUSH_PLATFORM_CALLERS_JSON. The X-Source-App you send must be allowed by that caller's policy.

Player notifications

• List → { "notifications": [ … ] } — all personal notifications, newest first, no pagination. Timestamps are RFC3339 UTC.
• Mark read / unread / delete → { "status": "success", "message": "…" }.
• Read-all / unread-all / delete-all → { "status": "success", "count": <n>, "message": "…" }.
• Errors use the FastAPI shape { "detail": "…" } — 400 (invalid user_id / id), 404 (not found). This differs from the web-push error envelope below.

Errors

Web-push and editor routes use this error envelope:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

details is optional. (Player notification routes use { "detail": "…" }, per above.)

Code	HTTP	Meaning
VALIDATION_ERROR	400	Request body or params failed validation
UNAUTHORIZED	401	Missing or invalid token / interaction token
FORBIDDEN	403	Caller policy rejected (route, X-Source-App, or tenant scope)
PUSH_ENV_NOT_READY	503	Push environment is not provisioned / ready
INTERNAL_ERROR	500	Unexpected server-side failure