What Is Protected Resource Metadata (PRM) and How It Works

Before OAuth, developers had to rely on documentation—or worse, guesswork—to know what tokens to use and which authorization servers to trust. OAuth standardized how APIs securely connect with clients, but there was still a gap: resource servers (the APIs themselves) didn’t have a standard for advertising their requirements.

This wasn’t an issue when OAuth 2.0 released in 2012. APIs tightly coupled with authorization servers, and integrations were simple. But today’s apps, AI agents, and standards like Model Context Protocol (MCP) expect to discover and connect to APIs at runtime—not through hard-coded configs. 

Enter OAuth 2.0 Protected Resource Metadata (PRM), published as RFC 9728. PRM gives APIs their own discovery document at a well-known URL, laying the foundation for more dynamic, secure integrations.

Let’s dive into what PRM is, why it matters now, and how it fits into today’s authorization landscape.

Main points

• Protected Resource Metadata (PRM) standardizes how APIs (resource servers) advertise access requirements using OAuth.

• PRM completes the trio of OAuth metadata standards, alongside Dynamic Client Registration and Authorization Server Metadata.

• PRM enables OAuth clients to discover authorization requirements automatically, without hard-coded configurations.

• The rise of AI agents, microservices, and dynamic integrations created a strong need for this standardized resource discovery.

What is Protected Resource Metadata?

Protected Resource Metadata (PRM) is a way for a protected resource, usually an API, to publish a machine-readable JSON document that explains:

• Which OAuth authorization servers it trusts

• What scopes it expects

• What token formats it requires

• Any special security requirements (like DPoP or mutual TLS)

This metadata is hosted at a well-known URL, typically under:

This lets OAuth clients dynamically fetch everything they need to know to request access, without guessing or relying on manual setup.

In short, PRM makes APIs self-describing, just like OAuth authorization servers have been for years.

Benefits of PRM: Why use it now?

When OAuth 2.0 launched, most applications were relatively simple: a known app connecting to a known API, tightly coupled with a known authorization server. Today's ecosystems look very different, and PRM provides a solution to deal with the complexity of modern API connections:

• AI agents, no-code platforms, and partner applications can dynamically discover and integrate with APIs at runtime, no human intervention or manual configuration required.

• APIs can specify whether they need a specific mechanism, like DPoP tokens, mTLS-bound tokens, or complex scopes

• Standardized methods for APIs to advertise their requirements enable more dynamic, autonomous operations from non-human identities (NHIs) like AI agents. 

Integration models like the Model Context Protocol (MCP) expect APIs to be self-describing–meaning an agent can learn how to authenticate and interact with a service by retrieving its metadata programmatically, not relying on hardcoded knowledge.

Without PRM, dynamic agentic integrations would be fragile, insecure, or impossible at scale. By allowing APIs to publish their OAuth requirements (e.g., expected scopes, trusted issuers, token presentation methods) in a machine-readable format, PRM enables this new class of dynamic, AI-driven, and federated integrations to happen securely.

Although early drafts of PRM surfaced around 2016, the ecosystem wasn’t ready then. Only with the explosion of microservices, zero-trust architectures, AI agents, and protocols like MCP did dynamic protected resource discovery become essential–and the time ripe for PRM to become a standardized part of OAuth.

How PRM fits into OAuth and API security

PRM fit seamlessly into the existing OAuth framework:

With PRM, all three major OAuth roles now have standardized discovery mechanisms. Before these mechanisms were defined, application developers had to manually implement all the connections. This usually meant reading documentation to decipher the right configuration.

For example, suppose you’re building an app that connects to a calendar API. Given the resource URL, you'd sift through the documentation of the site to find the auth server endpoint, which scopes to include, what they mean, and more. Then, you’d hardcode this into your system.

Now, imagine if the calendar API changed their security requirements. The client would break unless manually updated. PRM helps streamline the process with a single URL.

How Protected Resource Metadata works

At a technical level, PRM defines a JSON document that resource servers publish at a predictable .well-known URL.

Some key fields in the document include:

Let’s take the aforementioned example of an app that connects to a calendar API. Given just the resource URL, and instead of hard-coding which auth server to use or what scopes an action requires, your app could:

1. Discover the API’s resource metadata.

2. Learn that it accepts tokens from https://auth.example.com.

3. See that it expects the calendar.read and calendar.write scopes.

4. Know that DPoP proofs are required.

This all happens programmatically, without manual setup.

New features introduced by PRM

Beyond basic discovery, PRM adds new capabilities to the OAuth ecosystem:

• JWT-signed metadata: Resource metadata can optionally be packaged and signed as a JWT, making it verifiable by clients.

• Dynamic updates via WWW-Authenticate: Resource servers can return a resource_metadata link in HTTP 401 responses, helping clients dynamically adjust if requirements change.

• Better federation: APIs can list multiple trusted authorization servers, enabling broader interoperability.

These features make OAuth more adaptable, especially for environments like open ecosystems, cross-organizational APIs, or AI-driven integrations.

PRM and progressive scoping

Protected Resource Metadata also plays a key role in enabling progressive scoping, a model where clients request only the minimal set of OAuth scopes needed for a specific operation–and request more later if needed.

For this to work seamlessly, clients must understand:

• Which scopes are available

• Which scopes are required for a given resource

• How to interpret insufficient scope errors (e.g. `insufficient_scope` in a 403)

PRM supports this by allowing resource servers to advertise their supported scopes and security expectations in a machine-readable way. This means clients can dynamically adapt their scope requests based on metadata, rather than hardcoding or over-requesting scopes up front.

We will likely see insufficient scope error handling standardized within protocols that sit on top of this, like MCP.

Security best practices with PRM

PRM’s focus is security, but it's important to implement it carefully:

• Always serve metadata over HTTPS.

• Validate that the resource field matches the expected URL.

• Verify JWT signatures if using signed metadata.

• Use strict audience restrictions in tokens to prevent misuse.

• Be cautious of Server-Side Request Forgery (SSRF) risks when fetching arbitrary metadata URLs.

Following these practices ensures PRM can enhance your API security effectively.

A big step forward for OAuth interoperability

Protected Resource Metadata (PRM) is a major upgrade for the future of integration. As applications, AI agents, and microservices increasingly need to discover and connect to APIs on the fly, hard-coded configurations are no longer enough. PRM gives APIs a standardized, secure way to advertise how they expect to be accessed.

By enabling comprehensive OAuth metadata, PRM transforms APIs from static endpoints into self-describing, interoperable components of a dynamic, federated internet. If you’re building or securing APIs today, implementing PRM plays a key role in making your services discoverable, trustworthy, and ready for the agent-driven, zero-trust world ahead. 

For more developer updates from the world of authentication, access control, and AI, subscribe to our blog or follow us on LinkedIn.

*** This is a Security Bloggers Network syndicated blog from Descope Learning Center authored by Descope Learning Center. Read the original post at: https://www.descope.com/learn/post/prm