OAuth Protected Resource Metadata (RFC 9728) — how to make your site agent-ready

What it is

RFC 9728 defines protected-resource metadata — a JSON document that describes a resource's identifier, the authorization servers that can issue tokens for it, and the scopes required. It's the complement to RFC 8414: the former describes the auth server, this describes the thing being protected.

Why it matters

When an agent hits a 401 on your API, this tells it where to go get a token.
Without it, the agent has to guess or be told out of band.
Combined with MCP Server Cards and API Catalogs, it closes the loop for programmatic authorization.

Remediation Prompt

I want to improve my site's agent readiness. Please implement the following fix for OAuth Protected Resource Metadata (RFC 9728) across our codebase.

Instructions:
Please fix the OAuth Protected Resource Metadata (RFC 9728) issue on my site so it is agent-ready.

How we test it

Step	Method	URL
A	GET	`/.well-known/oauth-protected-resource`

Pass Warn Fail Matrix

Condition	Status	Score
Exists with `resource` + `authorization_servers` array (≥1)	pass	1.0
Exists but missing `authorization_servers`	warn	0.3
404	fail	0.0

Sub Tests

id	Weight	Pass when
`metadata-present`	0.5	200 + JSON
`points-to-authz-server`	0.5	≥1 URL in `authorization_servers`

Remediation Prompt

Please publish OAuth Protected Resource metadata at /.well-known/oauth-protected-resource per RFC 9728.

Minimum JSON shape:

    {
      "resource": "https://api.example.com",
      "authorization_servers": ["https://auth.example.com"],
      "scopes_supported": ["read:items", "write:items"],
      "bearer_methods_supported": ["header"],
      "resource_documentation": "https://docs.example.com/api"
    }

Also send the WWW-Authenticate header on 401 responses pointing at this document:

    WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"

Serve the JSON with Content-Type: application/json.

Common Mistakes

Resource URL mismatches the actual API base.
Listing an authorization server that isn't RFC 8414 compliant.
Not sending the WWW-Authenticate hint on 401.

References

RFC 9728: OAuth Protected Resource Metadata

Test Fixtures

pass.json
warn-no-authz.json
fail-404.json

← Previous Check

OAuth Authorization Server Metadata (RFC 8414)

Next Check →

OpenAPI Discovery