# Why Won't AI auth.md

Instructions for AI agents that want to use the Why Won't AI MCP server (`https://mcp.whywontai.com/`) or A2A endpoint (`https://mcp.whywontai.com/a2a`) for a person.

## Step 1: Discover

1. Read the protected resource metadata: `GET https://mcp.whywontai.com/.well-known/oauth-protected-resource`.
2. Read the authorization server metadata: `GET https://whywontai.com/.well-known/oauth-authorization-server`. The issuer is `https://whywontai.com`.
3. Read its `agent_auth` block: `skill`, `register_uri`, `claim_uri`, `revocation_uri` and `identity_types_supported` (only `anonymous`).

You need no credential for `check_robots`. It has a limit of 30 calls a day for each IP address. The other tools (`scan_site`, `get_scan`, `list_issues`, `list_scans`, `get_internal_links`) need a credential that a person has approved.

## Step 2: Pick a method

- **Your client supports OAuth (recommended):** use the authorization code flow with PKCE (S256). Register with `POST https://mcp.whywontai.com/oauth/register` (RFC 7591, public client, `token_endpoint_auth_method: none`). The person approves at `https://whywontai.com/oauth/authorize`. Exchange the code at `POST https://mcp.whywontai.com/oauth/token`. Scope: `scans`.
- **Your client does not support OAuth:** register anonymously (Step 3), then ask the person to claim the key (Step 4).
- **The person already has a key:** they can create one at https://whywontai.com/dashboard under MCP & API.

## Step 3: Register (anonymous)

```http
POST https://mcp.whywontai.com/agent/auth
Content-Type: application/json

{"identity_type": "anonymous", "agent_name": "your agent name"}
```

```json
{
  "credential": {"type": "access_token", "access_token": "wwai_...", "token_type": "Bearer", "scope": ""},
  "claim_token": "...",
  "claim_url": "https://whywontai.com/agent/claim?token=...",
  "claim_expires_at": "..."
}
```

Before a person claims it, the key has no scopes. It works like no credential (`check_robots` only). There is a limit of 10 registrations a day for each IP address.

## Step 4: Claim

Show `claim_url` to your person. They sign in at whywontai.com and approve. Then the same key gets the `scans` scope and uses the scan limits of their plan. The claim link expires after 7 days.

To get the link again:

```http
POST https://mcp.whywontai.com/agent/auth/claim
Content-Type: application/json

{"claim_token": "..."}
```

The claim happens in the browser, after the person signs in. We send no email codes.

## Step 5: Use the credential

Send it on every request: `Authorization: Bearer wwai_...`. A call that needs an account answers HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="https://mcp.whywontai.com/.well-known/oauth-protected-resource"`.

## Step 6: Revoke

```http
POST https://mcp.whywontai.com/agent/auth/revoke
Content-Type: application/json

{"token": "wwai_..."}
```

The person can also revoke any key in their dashboard. OAuth clients can use `POST https://mcp.whywontai.com/oauth/revoke` (RFC 7009).

## Not supported

- ID-JAG identity assertions and verified-email claims.
- Refresh tokens. Access tokens do not expire. They stop working when someone revokes them.

## Buy a plan for your person

The same credential can buy a prepaid plan pass for the account that owns it. You must have a claimed key or an OAuth token. Anonymous keys that nobody has claimed cannot buy.

Products (one-time payment, no auto-renew):

| Product | Price |
| --- | --- |
| `whywontai_starter_month` | $29 |
| `whywontai_starter_year` | $290 |
| `whywontai_pro_month` | $99 |
| `whywontai_pro_year` | $990 |
| `whywontai_agency_month` | $299 |
| `whywontai_agency_year` | $2,990 |

Rules:

- One pass at a time. Buy the same plan again to extend it.
- We refuse a pass when the account has a live subscription (code `already_subscribed`) or a paid plan from another source (code `plan_active`).
- Ask your person before you buy. Tell them the product and the price.

Protocols:

- **ACP:** discovery `https://whywontai.com/.well-known/acp.json`. `POST https://mcp.whywontai.com/acp/checkout_sessions` with an `Idempotency-Key` header, then `/complete` with a Stripe shared payment token (`spt_...`).
- **UCP:** discovery `https://whywontai.com/.well-known/ucp`. API `https://mcp.whywontai.com/ucp/v1/checkout-sessions`.
- **MPP:** `POST https://mcp.whywontai.com/mpp/plan-pass` with `{"product": "..."}`. The first call answers HTTP 402 with `WWW-Authenticate: Payment`. Send the credential in `Payment-Authorization`.
- **x402:** `POST https://mcp.whywontai.com/x402/plan-pass` (or `https://whywontai.com/api`). The first call answers HTTP 402 with `PAYMENT-REQUIRED`. Retry with `PAYMENT-SIGNATURE` and your bearer token. We check the token before we settle, so no payment is taken without a valid credential.
- **MCP:** the tool `get_plan_pass_quote` returns the signed-in account's plan and whether a pass can be bought. It does not take payment.

Catalog: `https://mcp.whywontai.com/commerce/catalog.json`. OpenAPI: `https://whywontai.com/openapi.json`.
