Client Authentication
Secure client-side API requests with signing keys and security modes
Client Authentication
The User API is designed for client-side use — it powers in-app inboxes, notification feeds, and preference screens. Because it runs in the browser, securing it requires two layers: authentication (proving who the user is) and allowed origins (restricting which domains can make requests).
This page covers authentication. See Allowed Origins for domain restrictions.
Security Modes
Notiflows supports two security modes for the User API:
Secure Mode (Recommended)
When Security Mode is enabled (default), each request requires:
x-notiflows-api-key— your project's public API keyx-notiflows-user-key— a JWT signed with your Application Signing Key (RS256)
Your backend signs JWTs with the private key. Notiflows verifies them with the public key stored in your project. The private key never leaves your infrastructure.
Development Mode
When Security Mode is disabled, each request requires:
x-notiflows-api-key— your project's public API keyx-notiflows-user-id— the user's external ID (no signing)
Development mode is NOT safe for production. Anyone with your API key can impersonate any user. Always enable Security Mode for production deployments.
Setting Up Signing Keys
- Go to Projects → Settings → API Keys
- Find the Client Authentication section
- Click Generate signing key
- Save the private key — it is only shown once
The private key is provided in two formats:
- Base64-encoded PEM — single-line, ideal for environment variables
- Raw PEM — standard format for file storage
Security Mode is enabled by default. If disabled, re-enable it in the same section.
Generating User Tokens
Your backend generates a JWT for each user. The token payload:
{
"sub": "user_external_id",
"iat": 1608600116,
"exp": 1608603716
}| Claim | Required | Description |
|---|---|---|
sub | Yes | The user's external ID (must match a user in Notiflows) |
iat | Recommended | Unix timestamp when the token was issued |
exp | Recommended | Unix timestamp when the token expires |
For code examples in Node.js, Python, and Ruby, see the Authentication API reference.
Best Practices
- Short-lived tokens — set expiry to 1 hour or less and implement token refresh
- Store keys securely — use environment variables or a secrets manager, never client-side code or version control
- Rotate keys when compromised — regenerating a key invalidates all existing tokens immediately
Next Steps
- Allowed Origins — Restrict which domains can call the User API
- Authentication API Reference — Full details with code examples