> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/koala73/worldmonitor/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField header="X-WorldMonitor-Key" type="string" required>
  Your World Monitor API key. Required for desktop apps and third-party integrations.
</ParamField>

### 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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```bash theme={null}
curl -H "X-WorldMonitor-Key: your-api-key-here" \
  "https://worldmonitor.app/api/seismology/v1/list-earthquakes"
```

```python theme={null}
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:

```bash theme={null}
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](/api/rate-limits))

4. **Request Processing**: Route to appropriate handler

## Error Responses

### Invalid API Key

```json theme={null}
{
  "error": "Invalid API key"
}
```

HTTP Status: `401 Unauthorized`

### Missing API Key (Required)

```json theme={null}
{
  "error": "API key required"
}
```

HTTP Status: `401 Unauthorized`

### Desktop Access Without Key

```json theme={null}
{
  "error": "API key required for desktop access"
}
```

HTTP Status: `401 Unauthorized`

### Origin Not Allowed

```json theme={null}
{
  "error": "Origin not allowed"
}
```

HTTP Status: `403 Forbidden`

## Security Best Practices

<Warning>
  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.
</Warning>

### 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

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Understand rate limiting and quotas
  </Card>

  <Card title="API Reference" icon="book" href="/api/introduction">
    Explore available endpoints
  </Card>
</CardGroup>