Multi-tenant mapping
This guide uses a generic SaaS product, example-app. Replace the example IDs with your own permanent identifiers.
Recommended mapping
Create one Notify application for each product environment. Inside each application, create a customer account for every customer organization or workspace.
| Source value | Notify value | Owner |
|---|---|---|
| Product and environment | Application registration | Tenant administrator |
| Organization primary key | Account external_key and request account_key | Your backend |
| User primary key | Notification recipient.external_user_id and token recipient_external_id | Your backend |
| Business event name | event_key | Your application |
| Business event ID and version | Idempotency-Key | Your application |
| Allowed Notify operations | Credential scopes | Notify defines names; authorized operator selects them |
The same user ID in two accounts represents two account-bound identities for inbox and user-token access.
Account lifecycle
Upsert PUT /v1/accounts/{external_key} when an organization is created and when its relevant metadata changes. Keep the identifier stable when the display name changes.
For a multi-tenant product, select application account mode required so requests must identify an account. A legacy/default account mode may allow account-less requests; do not use that as an implicit mapping for customer organizations.
Customer-specific channel connections
Configure SMTP, WAHA, or Discord on each account that sends through that channel. Account-bound delivery uses the exact account's provider; it does not fall back to an application-level provider when missing.
If customers intentionally share the same external service, provision the intended connection for each account explicitly. Store secrets as provider configuration, not account metadata.
Backend authority
Application keys are application-wide. Your backend must check customer membership for every user-triggered action. Do not give customer browsers the application's API key.
For browser access, issue a user token after verifying the active account and user. That token restricts the frontend to the selected recipient.
Continue with the Implementation guide for the required backend and frontend work.