Authentication

API authentication, API keys, and origin-based access control

Overview

World Monitor uses a hybrid authentication system that combines origin-based trust with optional API keys. The authentication strategy depends on where requests originate.

Authentication Methods

1. Trusted Browser Origins (No Key Required)

Requests from trusted browser origins do not require an API key:

Production Origins:

• https://worldmonitor.app
• https://*.worldmonitor.app (subdomains)
• https://worldmonitor-*-elie-*.vercel.app (Vercel previews)

Development Origins (NODE_ENV !== ‘production’):

• http://localhost:*
• http://127.0.0.1:*

Desktop App Origins:

• https://tauri.localhost:*
• https://*.tauri.localhost:*
• tauri://localhost
• asset://localhost

2. Desktop Applications (API Key Required)

Desktop applications always require a valid API key, even from tauri://localhost origins.

X-WorldMonitor-Key · string · required

Your World Monitor API key. Required for desktop apps and third-party integrations.

3. Third-Party Applications (API Key Required)

Requests from unknown origins or without an Origin header must provide a valid API key.

How to Authenticate

Browser Requests (Trusted Origins)

No authentication needed for same-origin requests:

const response = await fetch('https://worldmonitor.app/api/market/v1/list-market-quotes', {
  method: 'GET'
});
const data = await response.json();

Desktop App Requests

Include the X-WorldMonitor-Key header:

const response = await fetch('https://worldmonitor.app/api/military/v1/list-military-flights', {
  method: 'GET',
  headers: {
    'X-WorldMonitor-Key': 'your-api-key-here'
  }
});

Third-Party Integration

Include the API key header:

curl -H "X-WorldMonitor-Key: your-api-key-here" \
  "https://worldmonitor.app/api/seismology/v1/list-earthquakes"

import requests

headers = {
    'X-WorldMonitor-Key': 'your-api-key-here'
}

response = requests.get(
    'https://worldmonitor.app/api/cyber/v1/list-cyber-threats',
    headers=headers
)
data = response.json()

CORS Configuration

The API implements Cross-Origin Resource Sharing (CORS) with strict origin validation.

Allowed Origins

CORS headers are set based on the request origin:

• Trusted origins: Access-Control-Allow-Origin reflects the request origin
• Untrusted origins: Request is rejected with 403 Forbidden
• Missing origin: Falls back to https://worldmonitor.app

CORS Headers

All responses include:

Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-WorldMonitor-Key
Access-Control-Max-Age: 86400
Vary: Origin

Preflight Requests

The API handles OPTIONS preflight requests:

curl -X OPTIONS \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: GET" \
  "https://worldmonitor.app/api/market/v1/list-crypto-quotes"

Response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS

Authentication Flow

The API processes requests in this order:

1. Origin Check: Validate request origin against allowed patterns

   • If origin is disallowed → 403 Forbidden
   • If origin is missing → Continue to key validation

2. API Key Validation:

   • Desktop origin: API key required
   • Trusted browser origin: API key optional (if provided, must be valid)
   • Unknown origin: API key required
   • No origin + no key: 401 Unauthorized

3. Rate Limiting: Check IP-based rate limits (see Rate Limits)

4. Request Processing: Route to appropriate handler

Error Responses

Invalid API Key

{
  "error": "Invalid API key"
}

HTTP Status: 401 Unauthorized

Missing API Key (Required)

{
  "error": "API key required"
}

HTTP Status: 401 Unauthorized

Desktop Access Without Key

{
  "error": "API key required for desktop access"
}

HTTP Status: 401 Unauthorized

Origin Not Allowed

{
  "error": "Origin not allowed"
}

HTTP Status: 403 Forbidden

Security Best Practices

Never expose your API key in client-side code, public repositories, or browser JavaScript. API keys should only be used in server-side or desktop applications.

Key Management

• Environment Variables: Store keys in .env files (never commit to git)
• Rotation: Rotate keys periodically
• Scoping: Use different keys for different environments (dev, staging, prod)

Origin Validation

The API uses strict origin validation:

• Origin header from TCP connection (x-real-ip from Vercel/Cloudflare)
• Referer header as fallback for same-origin requests
• Client-settable headers like x-forwarded-for are ignored

Obtaining an API Key

API keys are currently issued manually. To request an API key:

1. Contact the World Monitor team
2. Provide your use case and expected request volume
3. Receive your API key via secure channel

Valid keys are configured in the WORLDMONITOR_VALID_KEYS environment variable (comma-separated list).

Next Steps

Rate Limits

Understand rate limiting and quotas

API Reference

Explore available endpoints