OAuth oauth.net

Protected Resource Metadata

RFC 9728 Published rfc-editor.org/rfc/rfc9728

Protected Resource Metadata defines a standard JSON document that an API publishes to describe itself to OAuth clients: which authorization servers it accepts tokens from, which scopes it uses, and how tokens should be presented. It lets a client start from nothing but the URL of an API and discover everything it needs to get an access token.

When to use this Publish a metadata document if you operate an API that clients can't be configured for in advance, for example when the same client software has to work with many independently deployed resource servers, or when your API can be paired with different authorization servers. The Model Context Protocol requires it, so an MCP client can find the right authorization server for any MCP server it's given.

The metadata document is a JSON object at a well-known URL derived from the resource identifier, /.well-known/oauth-protected-resource. For a resource with a path, the well-known string goes between the host and the path. The only required field is resource, which must match the resource identifier the client used to build the URL. The authorization_servers field lists the issuers the resource trusts, and the client then fetches each issuer's Authorization Server Metadata to find its endpoints. Other fields include scopes_supported, bearer_methods_supported, jwks_uri, and flags for DPoP and Mutual TLS bound tokens.

The spec also defines a resource_metadata parameter for the WWW-Authenticate response header. When a client makes a request without a valid token, the resource server's 401 response can point to its metadata document, so the client doesn't have to guess the URL:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata=
  "https://resource.example.com/.well-known/oauth-protected-resource"

The client fetches that URL and gets back a document such as:

{
  "resource": "https://resource.example.com",
  "authorization_servers": ["https://as.example.com"],
  "scopes_supported": ["profile", "email"],
  "bearer_methods_supported": ["header"]
}

Related specs