Scopes and permissions
A scope is a named permission attached to a credential. For example, notifications:send allows a backend to submit notifications. A valid key without that scope cannot use the send endpoint.
Who defines the scopes?
Notify defines and enforces the supported scope names. Your application does not invent Notify scopes. An authorized tenant team member or platform operator selects the required scopes when creating an application API key.
Your application's own roles, such as admin or member, remain part of your application. They are not automatically copied into Notify scopes. Your backend decides whether the current user may perform a business action; Notify then checks whether the backend credential may call the requested Notify operation.
Application API scopes
These nine scope names are the supported application-key allowlist.
| Scope | Allows | Typical reason to grant it |
|---|---|---|
accounts:manage | Create/update and read customer accounts through /v1/accounts | Synchronize organizations from your product |
notifications:send | Submit notifications and manually retry terminal deliveries | Send business notifications |
notifications:send_raw | Use direct subject/body content instead of requiring a template | Application-managed message content |
notifications:read | Read notification and delivery status | Track delivery outcomes |
templates:manage | Read/create templates and create template versions | Template automation |
providers:manage | Manage external provider configuration, including account provider tests | Configure SMTP, WAHA, or Discord |
inbox:read | Use application-key inbox routes, including their mark-read actions, and application realtime | Trusted backend inbox integration |
push:manage | Read push configuration and manage/test push subscriptions through application routes | Backend push integration |
users:token_issue | Create recipient-bound user tokens | Enable frontend inbox, SSE, and push access |
notifications:send_raw is an additional content permission. It does not replace notifications:send. Sending raw content requires both. Template-based sending requires notifications:send and a valid published template.
The current application inbox API uses inbox:read for both reading and marking items read. The recipient-token API separates these permissions.
Suggested key profiles
| Workload | Scopes |
|---|---|
| Send existing templates | notifications:send |
| Send raw messages | notifications:send, notifications:send_raw |
| Synchronize accounts, send templates, and track status | accounts:manage, notifications:send, notifications:read |
| Issue frontend user tokens | users:token_issue |
| Configure customer channel providers | providers:manage |
| Manage template content | templates:manage |
Combine profiles only when the same trusted workload needs them. A key with no provider-management scope can still send through providers already configured by an authorized operator.
User-token scopes
Notify currently issues user tokens with the fixed set below. The token request accepts account ID, recipient ID, and lifetime; it does not accept a custom scopes field.
| Scope | User API behavior |
|---|---|
inbox:read | Read inbox and unread count |
inbox:write | Mark inbox items read |
push:manage | Read push config and manage the recipient's subscriptions |
realtime:connect | Open the recipient's SSE stream |
A backend key needs users:token_issue to request this token. It does not need to hold all four user-token scopes itself. The signed token restricts access to its application, account, and recipient.
Platform scope and Console permissions
platform:admin belongs to platform credentials. It is not an available scope for application API keys.
Human Console users have role-based permissions such as credential creation or template publishing. Console roles and application-key scopes are separate permission systems.
What scopes do not do
An application key is application-wide; a scope is not a per-customer organization filter. For account-aware endpoints, Notify resolves account_key inside the key's application. Your backend must still authorize the signed-in user's membership before selecting an account or issuing a token.
An arbitrary string such as orders:approve is not a supported Notify scope. Keep that permission in your application's authorization system.
Diagnosing permission errors
401: the credential is missing, invalid, inactive, expired, or the wrong type.403 missing scope: ...: the credential passed authentication but lacks the endpoint permission.422 unsupported credential scope: credential creation included a name outside Notify's allowlist.
If a workload needs another permission, create a replacement credential with the appropriate scope set, deploy it to the backend, verify it, and revoke the old credential. Do not expand permissions just to bypass an unexplained error.