OAuth protected resource use cases

Three real jobs where the discovery pack matters. Each scenario names who owns the origin, what “done” looks like, and how it fails when clients cannot fetch PRM.

1. MCP HTTP server needing OAuth discovery

Who: A team shipping a remote MCP server at https://mcp.example.com/mcp that must reject anonymous tool calls and point agents at the correct authorization server.

Task: Publish path-inserted PRM and return resource_metadata on 401 so MCP clients can discover AS metadata without hardcoding.

  1. Open the generator. Set resource to https://mcp.example.com/mcp and AS issuer to your auth host.
  2. Confirm the derived URL is https://mcp.example.com/.well-known/oauth-protected-resource/mcp — not the host-root well-known alone.
  3. Deploy JSON + Pages headers on mcp.example.com. Wire 401 responses to copy the WWW-Authenticate line from the tool.
  4. Self-check with curl (see how-to) that resource matches and Content-Type is JSON.

Result when correct: Clients fetch PRM, then AS metadata, then complete OAuth without a hardcoded issuer.

Failure symptoms: Well-known only at host root; HTML 200 soft-404; resource missing a path segment; 401 without resource_metadata. Agents loop or show “unauthorized” with no discovery URL.

2. Multi-tenant API: one host, many resource paths

Who: Platform engineers hosting tenant APIs like https://api.example.com/t/acme and /t/globex that each trust different authorization servers.

Task: Publish a separate PRM document per resource path without colliding on a single host-root file.

  1. Generate one pack per tenant resource identifier (path included).
  2. Deploy each JSON under /.well-known/oauth-protected-resource/t/<tenant>.
  3. Ensure each tenant’s 401 challenge points at that tenant’s absolute metadata URL.
  4. Refuse to share one PRM across tenants that use different AS issuers.

Result: Each tenant’s clients discover the right AS; cross-tenant token confusion is harder.

Failure symptoms: All tenants share one root PRM listing every AS; clients accept tokens from the wrong issuer.

3. SDK / docs site: golden discovery pack for integrators

Who: SDK vendors documenting how customers become resource servers, or internal platform docs that ship a “golden” example pack.

Task: Give integrators a copy-paste discovery example without implying this site validates live production URLs or replaces their AS.

  1. Generate a fictional but schema-valid pack (for example https://docs-example.test/api) fully locally.
  2. In docs, label it clearly as protected resource metadata, not login UI and not token introspection.
  3. Tell customers they must replace hosts, publish real DNS/TLS, and operate their own AS.
  4. Never paste customer client secrets into demos; this tool never asks for secrets.
Boundary: If someone arrives looking for “OAuth login button” or “validate my live PRM URL,” send them away. This matrix only helps resource owners build discovery files RFC 9728 clients can fetch.