# auth.md

How an autonomous agent gets credentials for ChangeGamer (https://changegamer.ai).

## Audience

AI agents and automated clients that need the **paid** surface: premium
resource bodies, the full corpus file, or an AI-use licence. Everything else
on this site is free and needs no credential at all — see *What needs no
credential* below before you buy anything.

## Authentication method

A single opaque Bearer token, issued per purchase.

- **Scheme:** `Authorization: Bearer <key>`
- **Fallback header:** `x-api-key: <key>` (identical effect)
- **Key format:** opaque string, `cg_` prefix. Not a JWT — do not attempt to
  parse or introspect it.
- **Lifetime:** valid until revoked. No refresh, no rotation endpoint, no
  expiry claim.
- **Transport:** HTTPS only.

There is **no OAuth 2.0 or OpenID Connect flow**, and therefore no
authorization server, no `/authorize`, no token endpoint and no
`/.well-known/oauth-authorization-server` document. If your client requires
OAuth, it cannot authenticate here; use the purchase flow below instead.

## Registration / provisioning

Self-serve, no account, no human in the loop.

1. **Pay.** Open a checkout URL from the offer table below, or read them
   programmatically from [`/api/pricing.json`](https://changegamer.ai/api/pricing.json).
2. **Collect the key.** Stripe redirects to
   `https://changegamer.ai/key?session_id=<cs_live_...>`, which returns the key as JSON
   within seconds of payment (a browser that asks for `text/html` gets the
   same fields as a page). The same `session_id` can be re-fetched if the
   first response is lost.
3. **Use it.** Send `Authorization: Bearer <key>` on any gated request.

- **Registration endpoint:** `GET https://changegamer.ai/key?session_id=<stripe_session_id>`
- **Payment manifest (every method, machine-readable):** [`/api/payment.json`](https://changegamer.ai/api/payment.json)
- **Offer catalog:** [`/api/pricing.json`](https://changegamer.ai/api/pricing.json)
- **Licence terms (RSL, machine-readable):** [`/license.xml`](https://changegamer.ai/license.xml)
- **Human terms:** [`/resources/access-and-pricing`](https://changegamer.ai/resources/access-and-pricing)

## Offers

| Offer | Price | Billing | Unlocks |
|---|---|---|---|
| Starter key | 5 EUR | one-time | All current premium resources (data-formats, json-api, autonomous-operations) via Bearer/x-api-key header. Key valid until revoked. |
| Corpus license | 25 EUR | one-time | All current premium resources plus a full llms-full.txt corpus file with premium bodies and an RSL extended AI-use grant. |
| Enterprise license | 150 EUR | one-time | Everything in Corpus License plus commercial redistribution rights: embedding in commercial products and distribution of corpus-derived datasets within the licensee's organization. |
| Corpus Updates — Annual | 45 EUR | year | Same API key access plus corpus file and RSL internal AI-use grant as Corpus License, re-delivered at each annual renewal with the current premium resource set. |

## Discovering that you need a key

You do not have to guess. Request the resource without a credential and read
the answer:

```http
GET /resources/data-formats.md HTTP/1.1
Host: changegamer.ai

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
Link: <...>; rel="payment", <...>; rel="payment-manifest", <...>; rel="pricing", <...>; rel="license", <...>; rel="mcp-server"
Cache-Control: no-store

{
  "error": "payment_required",
  "resource": "data-formats",
  "price_usd": "0.05",
  "payment_url": "https://buy.stripe.com/fZu9AMa230eP2b1f0d7EQ00",
  "how_to_pay": "...",
  "terms": "https://changegamer.ai/resources/access-and-pricing.md",
  "license": "https://changegamer.ai/license.xml",
  "pricing_catalog": "https://changegamer.ai/api/pricing.json",
  "preview": { "title": "...", "description": "...", "sections": ["..."] }
}
```

The 402 body carries everything needed to complete the purchase and retry, and
the `Link` header carries the same pointers for clients that read headers
rather than bodies. Retry the identical request with the `Authorization`
header once you hold a key.

The full corpus (`/api/corpus.full.jsonl`, MCP `get_full_corpus`) answers its own 402: its
`payment_url` is the Corpus license checkout (https://buy.stripe.com/fZu28kgqr8Ll2b14lz7EQ01) and its `offers` field
lists the offers that unlock it (`corpus`, `enterprise`). A
Starter key gets the same 402, with `how_to_pay` saying which upgrade is needed.

## Over MCP

The MCP server at `https://changegamer.ai/mcp` (Streamable HTTP) needs **no credential to
connect**, and 14 tools are registered. Tools that return
paid content take an optional `api_key` argument and otherwise return the same
`payment_required` object the HTTP gate returns:

- `get_payment_info` — how to pay (no key needed)
- `get_pricing` — the offer catalog (no key needed)
- `check_access` — test a key before relying on it
- `get_resource(slug, api_key)` — premium body with a key
- `get_full_corpus(api_key)` — corpus deliverable, requires a corpus-tier key

Server card: [`/.well-known/mcp/server-card.json`](https://changegamer.ai/.well-known/mcp/server-card.json)

## On-chain payment (x402)

`GET https://changegamer.ai/api/x402/<slug>` implements the x402 standard for agents
holding a stablecoin wallet. It returns `503 x402_not_configured` while the
operator has not enabled settlement; probes are counted as demand. Until it is
live, the Stripe + Bearer flow above is the working rail.

## What needs no credential

Do not buy a key for any of this — it is free and always will be:

- [`/llms.txt`](https://changegamer.ai/llms.txt) and [`/llms-full.txt`](https://changegamer.ai/llms-full.txt)
- Every resource **page** at `/resources/<slug>`, including premium ones
  (premium pages serve a preview and section outline rather than the full body)
- Every article at `/articles/<slug>` and its `.md` variant — the editorial
  layer is never licensed
- The free resource set's `.md` and JSON variants
- [`/api/corpus.jsonl`](https://changegamer.ai/api/corpus.jsonl) — the full corpus with
  premium bodies stubbed
- Every index and catalog: `/api/resources.json`, `/api/articles.json`,
  `/api/search-index.json`, `/api/stats.json`, `/api/pricing.json`,
  `/api/payment.json`, `/openapi.json`, `/.well-known/api-catalog`
- The Agent-Readiness Grader: `POST /api/grader` with `{"url": "..."}`
- Connecting to the MCP server and calling its discovery tools

## Limits

Every limit the worker enforces, generated from the code at build time (the
same values as `limits` in
[`/.well-known/agent-access.json`](https://changegamer.ai/.well-known/agent-access.json)
and `info.x-limits` in [`/openapi.json`](https://changegamer.ai/openapi.json)):

| Limit | Value | Unit | Applies to | Over the limit |
|---|---|---|---|---|
| `mcp_max_body_bytes` | 1048576 | bytes | POST /mcp request body | HTTP 413, JSON-RPC error -32600 |
| `mcp_max_batch_messages` | 10 | messages | POST /mcp JSON-RPC batch | HTTP 400, JSON-RPC error -32600 |
| `mcp_list_articles_default_page` | 30 | rows | MCP list_articles without a `limit` argument | next_offset points at the next page |
| `mcp_list_articles_max_page` | 50 | rows | MCP list_articles `limit` argument | input validation error |
| `mcp_search_resources_max_results` | 50 | results | MCP search_resources `limit` argument | input validation error |
| `mcp_search_max_results` | 25 | results | MCP search `limit` argument | input validation error |
| `mcp_arg_slug_max_chars` | 200 | characters | MCP tool argument(s) slug, cluster, cluster_id | input validation error, nothing computed |
| `mcp_arg_query_max_chars` | 500 | characters | MCP tool argument(s) query, q | input validation error, nothing computed |
| `mcp_arg_api_key_max_chars` | 256 | characters | MCP tool argument(s) api_key | input validation error, nothing computed |
| `mcp_arg_category_max_chars` | 200 | characters | MCP tool argument(s) category | input validation error, nothing computed |
| `grader_max_body_bytes` | 16384 | bytes | POST /api/grader request body | HTTP 413 |
| `grader_target_max_bytes` | 200000 | bytes | each page the grader fetches from the graded site | read is cut at the limit |
| `grader_target_max_redirects` | 3 | redirects | redirect hops per grader fetch | that check fails |
| `key_session_id_max_chars` | 200 | characters | GET /key session_id parameter | HTTP 400 |
| `webhook_max_body_bytes` | 1048576 | bytes | POST /webhooks/stripe body (read before the signature check) | HTTP 413 {"error":"payload_too_large"} |
| `grader_calls_per_window` | 10 | calls | POST /api/grader, per client IP | HTTP 429 with Retry-After: 60 |
| `grader_window_seconds` | 60 | seconds | POST /api/grader, per client IP | HTTP 429 with Retry-After: 60 |
| `mcp_heavy_calls_per_window` | 20 | calls | MCP get_corpus without category, get_full_corpus, list_articles with full:true; per client IP | tool result with isError and error "rate_limited", retry_after_seconds 60 |
| `mcp_heavy_window_seconds` | 60 | seconds | MCP get_corpus without category, get_full_corpus, list_articles with full:true; per client IP | tool result with isError and error "rate_limited", retry_after_seconds 60 |

## Credential handling

- Send the key only to `changegamer.ai` over HTTPS. Never to a third party.
- Treat it as a secret: do not log it, do not embed it in a public repository,
  do not put it in a URL query string (use the header).
- Responses to keyed requests are returned `Cache-Control: private, no-store`.
  Do not write them to a shared cache.
- The Starter key grant is personal and non-transferable; the
  Corpus license adds an explicit AI-use grant. Redistribution rights require
  the enterprise offer. Full terms: [`/license.xml`](https://changegamer.ai/license.xml).
- Lost a key, or need it revoked? Reply to your Stripe receipt email (the
  same route the `/key` page names).
