Notification APIs
Unified notification API covering user-facing and management endpoints.
User-facing endpoints at POST /api/v1/notifications/<method> handle push device registration, in-app inbox, and notification preferences. User context is derived from authentication headers.
Management endpoints at POST /api/v1/notifications/manage/<method> handle sending notifications, managing topics, subscribers, workflows, providers, and environment promotion. Requires secret key (sk_*) or admin JWT authentication.
Field naming
Request bodies accept either snake_case or camelCase — both parse. Response bodies are
always camelCase (transactionId, unseenCount, subscriberId), because responses are
encoded with protojson. Fields that are unset, empty, zero, or false are omitted from the
response entirely rather than sent as null — read them with a default, not a presence check.
See the Notifications guide for push, in-app, email, SMS, and chat delivery — topics, digest, and workflow configuration.
Authentication
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: Bearer Auth
Your API key. sk_… for backend-to-backend calls, pk_… for client apps.
Never valid on its own — see the combinations under Security below.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
The end user this call acts for. Required with an sk_… key, because a secret
key identifies your tenant and not a user; omitting it returns
401 authenticated user_id is required. The key needs the users:impersonate
scope or the call fails with 403 insufficient_scope.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-On-Behalf-Of |
The end user's own JWT, issued by the OIDC provider configured on the
publishable key. Required alongside a pk_… key, and supplies the user
identity in place of X-On-Behalf-Of.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |