# Auth.md — Authenticating with Wander

Wander exposes both **open** and **protected** capabilities to agents.

## Open (no authentication)
- All HTML pages and their Markdown (`Accept: text/markdown`) variants
- `https://agentready-travel.agreatorganization.com/data/stays.json`, `https://agentready-travel.agreatorganization.com/data/flights.json`
- `https://agentready-travel.agreatorganization.com/feed/products.json` (ACP product feed)
- Read-only MCP tools (`search_stays`, `search_flights`, `get_stay`)

## Protected (OAuth 2.0)
Booking tools and the premium deals API require an OAuth 2.0 access token.

- Authorization server metadata: `https://agentready-travel.agreatorganization.com/.well-known/oauth-authorization-server` (RFC 8414)
- Protected resource metadata: `https://agentready-travel.agreatorganization.com/.well-known/oauth-protected-resource` (RFC 9728)
- Flow: Authorization Code + PKCE (S256). Dynamic client registration at `https://agentready-travel.agreatorganization.com/oauth/register`.
- Scopes: `mcp.read` (read catalog), `mcp.book` (create bookings).
- Present the token as `Authorization: Bearer <token>`.

Unauthenticated calls to protected resources return `401` with a
`WWW-Authenticate: Bearer resource_metadata="https://agentready-travel.agreatorganization.com/.well-known/oauth-protected-resource"` header.

## Agent registration flow (self-contained)
An autonomous agent can authenticate end-to-end without human help:

1. **Discover** the authorization server: `GET https://agentready-travel.agreatorganization.com/.well-known/oauth-authorization-server`
   (also exposes a machine-readable `agent_auth` block).
2. **Register** a client dynamically (RFC 7591):
   ```http
   POST https://agentready-travel.agreatorganization.com/oauth/register
   Content-Type: application/json

   { "client_name": "my-agent", "grant_types": ["authorization_code"], "token_endpoint_auth_method": "none" }
   ```
   The response contains a `client_id`.
3. **Authorize** with PKCE (S256): redirect to
   `https://agentready-travel.agreatorganization.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&code_challenge=...&code_challenge_method=S256&scope=mcp.read%20mcp.book`
   and receive an authorization `code`.
4. **Exchange** the code for a token:
   ```http
   POST https://agentready-travel.agreatorganization.com/oauth/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=authorization_code&code=CODE&client_id=CLIENT_ID&code_verifier=...
   ```
5. **Call** the protected resource with `Authorization: Bearer ACCESS_TOKEN` against `https://agentready-travel.agreatorganization.com/mcp`.

The same metadata in machine-readable form:

```json
{
  "agent_auth": {
    "version": "0.1",
    "registration": { "type": "dynamic_client_registration", "endpoint": "https://agentready-travel.agreatorganization.com/oauth/register" },
    "authorization": { "flow": "authorization_code", "pkce": "S256", "authorization_endpoint": "https://agentready-travel.agreatorganization.com/oauth/authorize", "token_endpoint": "https://agentready-travel.agreatorganization.com/oauth/token" },
    "protected_resource": "https://agentready-travel.agreatorganization.com/mcp",
    "scopes_supported": ["mcp.read", "mcp.book"]
  }
}
```

## Paid (x402 / MPP)
The premium real-time deal feed at `https://agentready-travel.agreatorganization.com/api/v1` is payable per request via
[x402](https://www.x402.org/) and the [Machine Payments Protocol](https://mpp.dev/).
It responds with `402 Payment Required` and a `WWW-Authenticate: Payment` challenge.