Authentication¶

Notifer supports multiple authentication methods depending on your use case.

Authentication Methods¶

1. No Authentication (Public Topics)¶

Public topics don't require authentication for publishing or subscribing:

# Publish to public topic
curl -d "Hello World" https://app.notifer.io/my-public-topic

# Subscribe to public topic
curl -N https://app.notifer.io/my-public-topic/sse

2. JWT Tokens (User Authentication)¶

Used for: - Creating/managing topics - Accessing private topics - Account management - Full API access

Getting a JWT Token¶

Email/Password Login:

curl -X POST https://app.notifer.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400
}

Google OAuth:

# Redirect user to:
https://app.notifer.io/auth/google

# After OAuth flow, you'll receive JWT tokens

Using JWT Tokens¶

Header Format:

curl https://app.notifer.io/api/topics \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameter (SSE/WebSocket only):

# For SSE subscriptions
curl -N "https://app.notifer.io/my-private-topic/sse?token=YOUR_ACCESS_TOKEN"

# For WebSocket connections
wscat -c "wss://app.notifer.io/my-private-topic/ws?token=YOUR_ACCESS_TOKEN"

Token Expiration¶

Access Token: Expires after 24 hours
Refresh Token: Expires after 30 days

Refreshing Tokens:

curl -X POST https://app.notifer.io/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

3. API Keys (Script Authentication)¶

API keys are long-lived tokens for scripts and integrations.

Creating an API Key¶

Via Web App: 1. Go to Settings → API Keys 2. Click "Create API Key" 3. Enter a name (e.g., "Production Server") 4. Copy the key (shown only once!)

Via API:

curl -X POST https://app.notifer.io/api/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expires_at": null
  }'

Response:

{
  "id": "uuid",
  "key": "noti_abc123...",
  "name": "Production Server",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": null,
  "last_used_at": null
}

Using API Keys¶

Header Format:

curl -d "Server is down!" \
  -H "X-API-Key: noti_abc123..." \
  https://app.notifer.io/alerts

Query Parameter:

curl -d "Message" "https://app.notifer.io/alerts?api_key=noti_abc123..."

API Key Features¶

✅ Long-lived (no expiration by default)
✅ Can be named for easy identification
✅ Can be revoked at any time
✅ Last used timestamp tracking
✅ Works for all API endpoints
⚠️ Full account access (use carefully!)

Best Practices¶

Name your keys - Use descriptive names (e.g., "CI/CD Pipeline", "Monitoring Server")
Rotate regularly - Create new keys and revoke old ones periodically
One key per service - Don't share keys across multiple services
Revoke unused keys - Delete keys you're no longer using
Use environment variables - Never commit keys to version control

4. Topic Access Tokens (Topic-Scoped Auth)¶

Topic access tokens provide limited access to a single topic.

Creating a Topic Access Token¶

Via Web App: 1. Go to topic page 2. Click Settings → Access Tokens 3. Click "Create Token" 4. Choose permissions (read/write) 5. Set expiration (optional)

Via API:

curl -X POST https://app.notifer.io/api/topics/my-topic/access-tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External Service",
    "permissions": ["read", "write"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response:

{
  "id": "uuid",
  "token": "tk_abc123...",
  "name": "External Service",
  "permissions": ["read", "write"],
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

Using Topic Access Tokens¶

Publishing:

curl -d "Message from external service" \
  -H "X-Topic-Token: tk_abc123..." \
  https://app.notifer.io/my-topic

Subscribing:

curl -N "https://app.notifer.io/my-topic/sse?token=tk_abc123..."

Permissions¶

read - Subscribe to messages, view history
write - Publish messages

When to Use Topic Tokens vs API Keys¶

Feature	Topic Token	API Key
Scope	Single topic	All topics
Permissions	Read/Write per token	Full access
Expiration	Optional	Optional
Use Case	Third-party access	Your own scripts
Security	Limited blast radius	Full account access

Recommendation: Use topic access tokens for granting limited access to external services or untrusted environments.

Authentication Comparison¶

Method	Use Case	Scope	Expiration
None	Public topics	Single topic	-
JWT	User actions, web/mobile apps	Full account	24h (access), 30d (refresh)
API Key	Scripts, CI/CD, servers	Full account	Optional
Topic Token	External services, limited access	Single topic	Optional

Security Best Practices¶

For JWT Tokens¶

✅ Store securely (never in localStorage for web apps)
✅ Use HTTPS only
✅ Refresh before expiration
✅ Implement token rotation

For API Keys¶

✅ Store in environment variables or secret managers
✅ Never commit to version control
✅ Use .env files with .gitignore
✅ Rotate periodically (e.g., every 90 days)
✅ Revoke immediately if compromised

For Topic Tokens¶

✅ Set expiration dates when possible
✅ Grant minimum required permissions (read-only when possible)
✅ Revoke when no longer needed
✅ Monitor usage via last_used_at

Code Examples¶

Python with JWT¶

import requests

# Login
response = requests.post('https://app.notifer.io/auth/login', json={
    'email': 'user@example.com',
    'password': 'password'
})
token = response.json()['access_token']

# Use token
headers = {'Authorization': f'Bearer {token}'}
requests.post('https://app.notifer.io/my-topic',
              data='Hello', headers=headers)

Python with API Key¶

import requests
import os

# Load from environment variable
API_KEY = os.environ['NOTIFER_API_KEY']

# Publish
requests.post('https://app.notifer.io/alerts',
              data='Server alert!',
              headers={'X-API-Key': API_KEY})

JavaScript/Node.js with JWT¶

const axios = require('axios');

// Login
const { data } = await axios.post('https://app.notifer.io/auth/login', {
  email: 'user@example.com',
  password: 'password'
});

const token = data.access_token;

// Use token
await axios.post('https://app.notifer.io/my-topic',
  'Hello',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
);

Bash with API Key¶

# Store in environment variable
export NOTIFER_API_KEY="noti_abc123..."

# Publish
curl -d "Deployment complete" \
  -H "X-API-Key: $NOTIFER_API_KEY" \
  https://app.notifer.io/deploys

Error Responses¶

401 Unauthorized¶

Missing Token:

{
  "detail": "Not authenticated"
}

Invalid Token:

{
  "detail": "Could not validate credentials"
}

Expired Token:

{
  "detail": "Token has expired"
}

403 Forbidden¶

Insufficient Permissions:

{
  "detail": "Insufficient permissions to access this topic"
}

Rate Limiting¶

Authentication affects rate limits:

Unauthenticated: 60 requests/minute per IP
Authenticated (JWT/API Key): Varies by subscription tier
Free: 60 requests/minute
Pro: 300 requests/minute
Team: 600 requests/minute

Next Steps¶

API Overview - Learn about available endpoints
API Reference - Complete endpoint documentation
API Keys Guide - Detailed API key management
Topic Access Tokens - Topic-scoped authentication
Private Topics - Access control configuration

Support¶

If you're having authentication issues:

Check your token hasn't expired
Verify you're using the correct header format
Ensure HTTPS (not HTTP) for production
Contact support: support@notifer.io