Authentication

Notifer supports multiple authentication methods depending on your use case.

Authentication Methods

1. Public Topics (Reading)

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:

Go to Settings → API Keys
Click "Create API Key"
Enter a name (e.g., "Production Server")
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 (Private Topics Only)

Topic access tokens provide limited access to a single private topic.

Private topics only

Topic access tokens are designed for private topics. For public topics, use an API key or JWT token instead.

Creating a Topic Access Token

Via Web App:

Go to topic page
Click Settings → Access Tokens
Click "Create Token"
Choose permissions (read/write)
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	Private topic sharing	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/subscribing public topics	Public 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:

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

Authentication Methods​

1. Public Topics (Reading)​

2. JWT Tokens (User Authentication)​

Getting a JWT Token​

Using JWT Tokens​

Token Expiration​

3. API Keys (Script Authentication)​

Creating an API Key​

Using API Keys​

API Key Features​

Best Practices​

4. Topic Access Tokens (Private Topics Only)​

Creating a Topic Access Token​

Using Topic Access Tokens​

Access Levels​

When to Use Topic Tokens vs API Keys​

Authentication Comparison​

Security Best Practices​

For JWT Tokens​

For API Keys​

For Topic Tokens​

Code Examples​

Python with JWT​

Python with API Key​

JavaScript/Node.js with JWT​

Bash with API Key​

Error Responses​

401 Unauthorized​

403 Forbidden​

Rate Limiting​

Next Steps​

Support​

Authentication Methods

1. Public Topics (Reading)

2. JWT Tokens (User Authentication)

Getting a JWT Token

Using JWT Tokens

Token Expiration

3. API Keys (Script Authentication)

Creating an API Key

Using API Keys

API Key Features

Best Practices

4. Topic Access Tokens (Private Topics Only)

Creating a Topic Access Token

Using Topic Access Tokens

Access Levels

When to Use Topic Tokens vs API Keys

Authentication Comparison

Security Best Practices

For JWT Tokens

For API Keys

For Topic Tokens

Code Examples

Python with JWT

Python with API Key

JavaScript/Node.js with JWT

Bash with API Key

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Next Steps

Support