Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us