Notification APIs
Register devices, read inbox messages and manage notification preferences, workflows and dispatch. Provider and channel availability depend on deployment configuration.
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Public management operations under /manage/ belong in trusted backend tooling. The API accepts a verified backend key or configured standalone JWT for tenant-context management; it does not enforce an operation-specific admin role or permission there. Do not treat this acceptance as a secure admin authorization contract. Restrict access at your application boundary. Get/update/delete of the caller’s subscriber profile still require user context.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
Send acknowledgements mean the provider accepted a trigger, not that a recipient received or read it. Preference state, channel registration and topic membership do not by themselves establish consent or sending authority.
Related guide: Notifications
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Authentication
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: Bearer Auth
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
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 |
JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |
📄️ Overview
Register devices, read inbox messages and manage notification preferences, workflows and dispatch. Provider and channel availability depend on deployment configuration.
📄️ Inbox state and actions
overview}
📄️ Preferences and channel inheritance
overview}
📄️ Push registration and topic delivery
overview}
🗃️ Endpoints
48 items
🗃️ Models
19 items
Document ID: DOC-CP-notifications-api-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-CP-notifications-api-overview#overview |
| JSON conventions | DOC-CP-notifications-api-overview#json-conventions |
| Authentication | DOC-CP-notifications-api-overview#authentication |