Concepts and glossary
The data model
A Notify tenant owns one or more applications. An application represents one integration in one environment. Its customer accounts represent the organizations inside your product.
The example names are placeholders. Replace them with identifiers from your own system.
Identity and ownership
| Term | Meaning | Example |
|---|---|---|
| Notify tenant | The organization that owns configuration, team access, and applications in Notify | Your company or business unit |
| Application | One product integration registered in Notify for a particular environment; it is not a browser session or a customer organization | example-app / staging |
| Environment | The deployment boundary an application belongs to | staging or production |
| Customer account | An organization or workspace inside the integrating product | A customer company using your SaaS |
external_key | Your stable organization ID when creating a customer account | org-123 |
account_key | The same external account identifier supplied in notification and user-token requests | org-123 |
| Recipient | The person or destination receiving a notification within an account | A signed-in customer user |
external_user_id | Your stable user ID in a notification's recipient object | user-42 |
recipient_external_id | The same user identifier when requesting a user token | user-42 |
A customer tenant in your SaaS usually maps to a customer account, not another Notify tenant. Use one application per product and environment, then create accounts for its customer organizations.
Use permanent database IDs or UUIDs. Organization names, email addresses, and phone numbers can change and should not be used as stable account or user identifiers.
Delivery vocabulary
| Term | Meaning | Example |
|---|---|---|
| Notification | One accepted message request for a recipient and business event | An invoice payment confirmation |
| Delivery | One channel-specific attempt stream belonging to that notification | The email delivery and the in-app delivery |
| Channel | The way a message reaches the recipient; channel names are defined by Notify | email, whatsapp, discord, in_app, web_push |
| Provider | The configured external service connection that sends a channel's messages | SMTP for email, WAHA for WhatsApp, a Discord webhook |
| Template | Reusable message content identified by template_key | invoice.paid |
| Template version | Published content for a channel and locale | Email content for en-US |
| Variables | Values inserted into template placeholders | Invoice number and customer name |
| Event key | Your application's name for the business event; you define this vocabulary | billing.invoice.paid |
| Routing rule | Notify configuration mapping an event key to channels | Invoice paid → email and in-app |
| Idempotency key | A stable identifier that prevents a retried request from creating another notification in the same application/account/environment | invoice-paid-INV-10001-v1 |
| Inbox | Persistent in-app messages shown inside your product | A notification panel |
| SSE | An open HTTP stream used to tell a connected frontend about live events | Refresh the inbox when a new item arrives |
| Web Push | Browser delivery using a service worker and a push subscription | An OS/browser notification |
| VAPID | Server identity keys used for Web Push | A public key exposed to the browser and a private key kept by Notify |
A channel and a provider are different: email is the channel; a configured SMTP connection is its provider. In-app delivery is built in and needs no external provider. Web Push needs platform VAPID configuration and a browser subscription.
Security vocabulary
| Term | Meaning |
|---|---|
| Credential | A secret proving which caller is making a request |
| Application API key | A backend credential bound to one application and a selected set of scopes |
| Scope | A Notify-defined permission such as notifications:send; see Scopes and permissions |
| User token | A short-lived signed credential bound to one application, account, and recipient |
| Console session | The credential created by Console login for Console operations |
| Platform administrator key | A platform-wide provisioning credential for the Admin API |
| Bearer | The HTTP authorization scheme: Authorization: Bearer <credential> |
| Role | A collection of permissions for a human Console team member; separate from API-key scopes |
Who defines what?
Notify defines channels, endpoint contracts, supported scopes, and the credential model. Your application supplies its organization IDs, user IDs, business event names, and business authorization rules. An authorized team member selects API-key scopes from Notify's supported list.