mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
e4c95ad9be
* docs(mintlify): cover MCP, OAuth, non-RPC endpoints, and usage Audit against api/ + proto/ revealed 9 OpenAPI specs missing from nav, the scenario/v1 service undocumented, and MCP (32 tools + OAuth 2.1 flow) with no user-facing docs. The stale Docs_To_Review/API_REFERENCE.md still pointed at pre-migration endpoints that no longer exist. - Wire 9 orphaned specs into docs.json: ConsumerPrices, Forecast, Health, Imagery, Radiation, Resilience, Sanctions, Thermal, Webcam - Hand-write ScenarioService.openapi.yaml (3 RPCs) until it's proto-backed (tracked in issue #3207) - New MCP page with tool catalog + client setup (Claude Desktop/web, Cursor) - New MDX for OAuth, Platform, Brief, Commerce, Notifications, Shipping v2, Proxies - New Usage group: quickstart, auth matrix, rate limits, errors - Remove docs/Docs_To_Review/API_REFERENCE.md and EXTERNAL_APIS.md (referenced dead endpoints); add README flagging dir as archival * docs(mintlify): move scenario docs out of generated docs/api/ tree The pre-push hook enforces that docs/api/ is proto-generated only. Replace the hand-written ScenarioService.openapi.yaml with a plain MDX page (docs/api-scenarios.mdx) until the proto migration lands (tracked in issue #3207). * docs(mintlify): fix factual errors flagged in PR review Reviewer caught 5 endpoints where I speculated on shape/method/limits instead of reading the code. All fixes cross-checked against the source: - api-shipping-v2: route-intelligence is GET with query params (fromIso2, toIso2, cargoType, hs2), not POST with a JSON body. Response shape is {primaryRouteId, chokepointExposures[], bypassOptions[], warRiskTier, disruptionScore, ...}. - api-commerce: /api/product-catalog returns {tiers, fetchedAt, cachedUntil, priceSource} with tier groups free|pro|api_starter| enterprise, not the invented {currency, plans}. Document the DELETE purge path too. - api-notifications: Slack/Discord /oauth/start are POST + Clerk JWT + PRO (returning {oauthUrl}), not GET redirects. Callbacks remain GET. - api-platform: /api/version returns the latest GitHub Release ({version, tag, url, prerelease}), not deployed commit/build metadata. - api-oauth + mcp: /api/oauth/register limit is 5/60s/IP (match code), not 10/hour. Also caught while double-checking: /api/register-interest and /api/contact are 5/60min and 3/60min respectively (1-hour window, not 1-minute). Both require Turnstile. Removed the fabricated limits for share-url, notification-channels, create-checkout (they fall back to the default per-IP limit). * docs(mintlify): second-round fixes — verify every claim against source Reviewer caught 7 more cases where I described API behavior I hadn't read. Each fix below cross-checked against the handler. - api-commerce (product-catalog): tiers are flat objects with monthlyPrice/annualPrice/monthlyProductId/annualProductId on paid tiers, price+period for free, price:null for enterprise. There is no nested plans[] array. - api-commerce (referral/me): returns {code, shareUrl}, not counts. Code is a deterministic 8-char HMAC of the Clerk userId; binding into Convex is fire-and-forget via ctx.waitUntil. - api-notifications (notification-channels): actual action set is create-pairing-token, set-channel, set-web-push, delete-channel, set-alert-rules, set-quiet-hours, set-digest-settings. Replaced the made-up list. - api-shipping-v2 (webhooks): alertThreshold is numeric 0-100 (default 50), not a severity string. Subscriber IDs are wh_+24hex; secret is raw 64-char hex (no whsec_ prefix). POST registration returns 201. Added the management routes: GET /{id}, POST /{id}/rotate-secret, POST /{id}/reactivate. - api-platform (cache-purge): auth is Authorization: Bearer RELAY_SHARED_SECRET, not an admin-key header. Body takes keys[] and/or patterns[] (not {key} or {tag}), with explicit per-request caps and prefix-blocklist behavior. - api-platform (download): platform+variant query params, not file=<id>. Response is a 302 to a GitHub release asset; documented the full platform/variant tables. - mcp: server also accepts direct X-WorldMonitor-Key in addition to OAuth bearer. Fixed the curl example which was incorrectly sending a wm_live_ API key as a bearer token. - api-notifications (youtube/live): handler reads channel or videoId, not channelId. - usage-auth: corrected the auth-matrix row for /api/mcp to reflect that OAuth is one of two accepted modes. * docs(mintlify): fix Greptile review findings - mcp.mdx: 'Five' slow tools → 'Six' (list contains 6 tools) - api-scenarios.mdx: replace invalid JSON numeric separator (8_400_000_000) with plain integer (8400000000) Greptile's third finding — /api/oauth/register rate-limit contradiction across api-oauth.mdx / mcp.mdx / usage-rate-limits.mdx — was already resolved in commit4f2600b2a(reviewed commit waseb5654647).
89 lines
3.8 KiB
Plaintext
89 lines
3.8 KiB
Plaintext
---
|
|
title: "Authentication"
|
|
description: "Three auth modes — browser origin, API key, and OAuth bearer — plus how server-side enforcement works."
|
|
---
|
|
|
|
WorldMonitor has **three** authentication modes. Which one applies depends on how you're calling.
|
|
|
|
## Auth matrix
|
|
|
|
| Mode | Header | Used by | Trusted on which endpoints? |
|
|
|------|--------|---------|------------------------------|
|
|
| **Browser origin** | `Origin: https://www.worldmonitor.app` (browser-set) | Dashboard, desktop app | Most public endpoints — but **not** `forceKey: true` routes. |
|
|
| **API key** | `X-WorldMonitor-Key: wm_live_...` | Server-to-server, scripts, SDKs | All endpoints, including `forceKey: true`. |
|
|
| **OAuth bearer** | `Authorization: Bearer <oauth-token>` | MCP clients (Claude, Cursor, Inspector) | `/api/mcp`. The handler also accepts a direct `X-WorldMonitor-Key` in lieu of an OAuth token — see [MCP](/mcp#authentication). |
|
|
| **Clerk session JWT** | `Authorization: Bearer <clerk-jwt>` | Authenticated browser users | User-specific routes: `/api/latest-brief`, `/api/user-prefs`, `/api/notification-channels`, `/api/brief/share-url`, etc. |
|
|
|
|
## `forceKey: true` — which endpoints ignore browser origin?
|
|
|
|
Some endpoints explicitly reject the "trusted browser origin" shortcut and require a real API key even from inside the dashboard:
|
|
|
|
- `/api/v2/shipping/route-intelligence`
|
|
- `/api/v2/shipping/webhooks`
|
|
- `/api/widget-agent`
|
|
- Vendor / partner endpoints
|
|
|
|
For these, you **must** send `X-WorldMonitor-Key`.
|
|
|
|
## Browser origin mode
|
|
|
|
CORS and `validateApiKey` together decide whether a given `Origin` is trusted. The allowlist is centralized in `api/_cors.js`.
|
|
|
|
- Allowed origins get `Access-Control-Allow-Origin: <echoed>` and pass the key check.
|
|
- Disallowed origins get no CORS header (browser rejects) and fail the key check.
|
|
|
|
See [CORS](/cors) for the origin patterns.
|
|
|
|
<Warning>
|
|
**A Cloudflare Worker** (`api-cors-preflight`) is the authoritative CORS handler for `api.worldmonitor.app` — it overrides `_cors.js` and `vercel.json`. If you're changing origin rules, change them in the Cloudflare dashboard.
|
|
</Warning>
|
|
|
|
## API key mode
|
|
|
|
### Generate a key
|
|
|
|
PRO subscribers get a key automatically on subscription. To rotate, contact support.
|
|
|
|
### Use it
|
|
|
|
```
|
|
X-WorldMonitor-Key: wm_live_abcdef0123456789...
|
|
```
|
|
|
|
Minimum 16 characters. Keep keys out of client-side code — use a server-side proxy if you need to call from the browser to a `forceKey` endpoint.
|
|
|
|
### Server-side validation
|
|
|
|
The edge function calls `validateApiKey(req, { forceKey?: boolean })`:
|
|
|
|
1. If `forceKey` is false AND the origin is trusted → pass.
|
|
2. Else, check `X-WorldMonitor-Key` against `WORLDMONITOR_VALID_KEYS` (env).
|
|
3. Also check the caller's entitlement cache (`invalidate-user-api-key-cache` flushes this).
|
|
4. If neither passes → 401.
|
|
|
|
## OAuth bearer (MCP only)
|
|
|
|
Full flow documented at [OAuth 2.1 Server](/api-oauth). For client setup, see [MCP](/mcp).
|
|
|
|
## Clerk session (authenticated dashboard)
|
|
|
|
The dashboard exchanges Clerk's `__session` cookie for a JWT and sends it on user-specific API calls:
|
|
|
|
```
|
|
Authorization: Bearer eyJhbGc...
|
|
```
|
|
|
|
Server-side verification uses `jose` with a cached JWKS — no round-trip to Clerk per request. Implemented in `server/auth-session.ts`. See [Authentication overview](/authentication) for full details.
|
|
|
|
## Entitlement / tier gating
|
|
|
|
Valid key ≠ access. Every PRO-gated endpoint also checks the caller's entitlement via `isCallerPremium(req)` before returning data.
|
|
|
|
| Tier | Access |
|
|
|------|--------|
|
|
| Anonymous | Public reads only (conflicts, natural disasters, markets basics) |
|
|
| Signed-in free | Same as anonymous + user preferences |
|
|
| PRO | All endpoints, MCP, AI Brief, Shipping v2, Scenarios |
|
|
|
|
Tier is resolved from Convex on each call, so a subscription change takes effect on the next request (after cache invalidation).
|