Authentication

Notifer supports multiple authentication methods depending on your use case.

Authentication Methods

1. Public Topics (Reading Only)

Public topics allow subscribing and reading messages without authentication:

# Subscribe to public topic (no auth needed)
curl -N https://app.notifer.io/my-public-topic/sse

Publishing Requires Authentication

Even for public topics, publishing messages always requires authentication (JWT, API key, or topic token). Only reading/subscribing to public topics is open.

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",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "username"
  }
}

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 30 minutes
• Refresh Token: Expires after 7 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",
    "access_level": "read_write",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response:

{
  "id": "uuid",
  "token": "tk_abc123...",
  "name": "External Service",
  "access_level": "read_write",
  "can_read": true,
  "can_write": true,
  "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..."

Access Levels

• read - Subscribe to messages, view history
• write - Publish messages only
• read_write - Both read and publish

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	Reading public topics	Single topic (read only)	-
JWT	User actions, web/mobile apps	Full account	30min (access), 7d (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: 10 messages/minute
  • ESSENTIALS: 30 messages/minute
  • TEAM: 100 messages/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:

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