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.
- It sends unauthenticated requests to
<your origin>/api/andhttps://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-resourcefile, the audit checks it against your origin (resourcemust match<origin>/) and runs the same chain from there. - For a 401 it uses the
resource_metadataURL from aWWW-Authenticate: Bearerchallenge. Without one it tries/.well-known/oauth-protected-resourcewith the resource path inserted, then at the root. The crawled root file is tried after the 401 probes. - 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
resourcethat is on the same origin as the requested URL and whose path is a prefix of the requested path, and a non-emptyauthorization_serversarray of strings. - For each listed issuer it requests
/.well-known/oauth-authorization-server(path inserted for issuers with a path), then the OpenID Connectopenid-configurationlocations. A document counts when itsissuermatches (a trailing slash on an origin-only issuer is tolerated) and it has bothauthorization_endpointandtoken_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-serverwhose 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.
- Make the API answer unauthenticated requests with
401and point to the metadata. If you only serve a root file for the whole origin, skip to step 2 and setresourcetohttps://example.com/:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/api"
- Serve that JSON, with a JSON content type.
resourcemust be the identifier of the resource the client called:
{
"resource": "https://example.com/api",
"authorization_servers": ["https://auth.example.com"]
}
- Make sure the authorization server publishes its own metadata with
issuer,authorization_endpointandtoken_endpointathttps://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.