OAuth discovery chain: what the check tests and how to fix it

Weight 3. Follows a 401 or a root protected resource metadata file (RFC 9728) to authorization server metadata (RFC 8414). Skipped if no API or MCP.

Agent Auth · Weight 3 in the w2agent Score

How common is it?

28% of 472 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

The audit tries to walk the chain an OAuth client would walk: protected resource, then its metadata, then the authorization server.

  1. It sends unauthenticated requests to <your origin>/api/ and https://api.<last two labels of your hostname>/, and also uses the response to the audit's MCP handshake if one was recorded. A 401 response starts a chain; a 200 or 403 does not. A second entry path needs no 401: if the audit's crawl found a root /.well-known/oauth-protected-resource file, the audit checks it against your origin (resource must match <origin>/) and runs the same chain from there.
  2. For a 401 it uses the resource_metadata URL from a WWW-Authenticate: Bearer challenge. Without one it tries /.well-known/oauth-protected-resource with the resource path inserted, then at the root. The crawled root file is tried after the 401 probes.
  3. Each fetch must answer 200 with a JSON content type, at most 256 KB and 5 seconds, within 15 seconds for the whole chain. The document needs a string resource that is on the same origin as the requested URL and whose path is a prefix of the requested path, and a non-empty authorization_servers array of strings.
  4. For each listed issuer it requests /.well-known/oauth-authorization-server (path inserted for issuers with a path), then the OpenID Connect openid-configuration locations. A document counts when its issuer matches (a trailing slash on an origin-only issuer is tolerated) and it has both authorization_endpoint and token_endpoint.
  • Pass: the whole chain resolved.
  • Partial: valid protected resource metadata but no usable authorization server, or no protected resource metadata but a valid root /.well-known/oauth-authorization-server whose issuer is your origin.
  • Fail: neither; the message lists what broke.
  • Skip: replaces a fail when the public API check failed or was skipped and no MCP endpoint was found. A pass or partial is kept even then.

The audit is looser than RFC 9728 section 3.3, which asks for an identical resource value; it accepts a path prefix, as MCP client SDKs do.

Why it matters to agents

An agent that meets a 401 needs to learn where to get a token without a human reading your docs. RFC 9728 defines the metadata document and the resource_metadata parameter for that, and RFC 8414 defines the document that describes the authorization server's endpoints. The MCP authorization specification (2026-07-28) requires MCP servers to implement protected resource metadata and requires clients to use it to find the authorization server.

If you have no API behind a login and no MCP server, there is nothing to discover and this check does not apply to you.

How to fix it

Do these in order. The audit starts from a 401 on the API or MCP endpoint, or from a root /.well-known/oauth-protected-resource file whose resource is your origin. Pick the path that matches your setup; the first step below covers the 401 path.

  1. Make the API answer unauthenticated requests with 401 and point to the metadata. If you only serve a root file for the whole origin, skip to step 2 and set resource to https://example.com/:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/api"
  1. Serve that JSON, with a JSON content type. resource must be the identifier of the resource the client called:
{
  "resource": "https://example.com/api",
  "authorization_servers": ["https://auth.example.com"]
}
  1. Make sure the authorization server publishes its own metadata with issuer, authorization_endpoint and token_endpoint at https://auth.example.com/.well-known/oauth-authorization-server. If you use a hosted identity provider, check its documentation for this URL rather than writing the file yourself.

Request each URL after deploying and confirm the status, content type and that issuer is identical to the authorization server identifier you listed in authorization_servers (RFC 8414 section 3.3), not to the /.well-known/ URL you fetched. Single-purpose follow-ups have their own pages: PKCE S256, Client ID Metadata Documents and MCP authorization.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →