# auth.md

> Agent registration and authentication manifest for The World Now (https://www.the-world-now.com).
> Audience: AI agents, MCP clients, and automated integrations. Humans should
> start at https://www.the-world-now.com/developers instead.

The World Now exposes public news, event, and market-intelligence APIs plus a
native MCP server. Most read endpoints work without any credential. This
document is the procedural recipe: discover -> pick a method -> register ->
use credentials -> handle limits and revocation.

## Step 1 — Discover

Fetch the OAuth discovery documents:

- Protected Resource Metadata (RFC 9728): https://www.the-world-now.com/.well-known/oauth-protected-resource
- Authorization Server Metadata (RFC 8414): https://www.the-world-now.com/.well-known/oauth-authorization-server

The Authorization Server metadata includes an `agent_auth` block pointing
back to this file, the registration endpoint, and the supported identity and
credential types. Machine-readable capability documents:

- Agent card: https://www.the-world-now.com/.well-known/agent-card.json
- MCP server card: https://www.the-world-now.com/.well-known/mcp/server-card.json
- Agent skills index: https://www.the-world-now.com/.well-known/agent-skills/index.json
- API catalog (RFC 9727): https://www.the-world-now.com/.well-known/api-catalog

## Step 2 — Pick a method

| Your situation | Method | Go to |
| --- | --- | --- |
| Read-only calls within free quotas | `anonymous` — no registration | Step 4 |
| Over free quota, one-off calls, crypto wallet available | `x402_payment` — pay per call | Step 5 |
| Recurring usage, want stable quotas and higher tiers | `api_key` — register a key | Step 3 |

## Step 3 — Register (api_key)

Registration endpoint: `POST https://www.the-world-now.com/api/catalyst/v1/keys`

API keys are claimed through a human sign-in ceremony: key creation requires
an authenticated browser session (Google OAuth or email credentials via
NextAuth). There is no unauthenticated dynamic client registration. Flow:

1. Hand off to your human: send them to https://www.the-world-now.com/developers and ask them
   to sign in and create an API key (organization name required).
2. The key is shown exactly once, format `cat_live_<48 hex chars>`. Store it
   securely; only a bcrypt hash is retained server-side.
3. One active key per account email. A second create returns `409`.

Key management (same session auth):

- Inspect keys + today's usage: `GET https://www.the-world-now.com/api/catalyst/v1/keys/mine`
- Revoke a key: `DELETE https://www.the-world-now.com/api/catalyst/v1/keys/mine?keyId=<id>`
- Upgrade tier (Stripe): `POST https://www.the-world-now.com/api/catalyst/v1/billing/checkout`

## Step 4 — Use credentials

Anonymous callers need no header; quotas are tracked per IP. Key holders send
the key as a Bearer token:

```
GET https://www.the-world-now.com/api/catalyst/v1/risk-index
Authorization: Bearer cat_live_...
```

Every response carries `X-Quota-*` headers with remaining daily quota.
Daily limits (UTC day): free tier 100 news /
10 finance calls; Builder tier
($9/mo)
2000 news / 500 finance.
Invalid or revoked keys are rejected — they are never silently downgraded to
anonymous.

The MCP server at https://www.the-world-now.com/api/mcp (streamable HTTP) accepts the same
optional Bearer credential and works anonymously within free quotas.

## Step 5 — Pay per call (x402)

Exhausted quotas on paid endpoints return `HTTP 402` with an
`accepts` array describing an x402 payment challenge (USDC on Base).
Retry the request with an `X-PAYMENT` header per the x402 spec
(https://www.x402.org/) to settle per call — no registration required.

## Revocation

- Self-service: `DELETE https://www.the-world-now.com/api/catalyst/v1/keys/mine?keyId=<id>`
  immediately deactivates the key.
- Compromised or abusive keys may be revoked server-side; subsequent calls
  return `401`.

## Errors

| Status | Where | Meaning / remedy |
| --- | --- | --- |
| 401 | Any protected call | Missing/invalid/revoked credential — re-register via Step 3 |
| 402 | Paid endpoints over quota | Pay via x402 (Step 5) or upgrade tier |
| 409 | POST /api/catalyst/v1/keys | Account already has an active key — reuse or revoke it |
| 429 | Any API call | Quota or rate limit hit — respect X-Quota-* headers and retry after UTC midnight |

## Contact

Questions or higher-volume needs: hello@the-world-now.com