OAuth discovery for AI agents: RFC 9728 and RFC 8414 metadata

Why does OAuth discovery matter for AI agents?

Some agent tasks need the shopper’s account: checking an order, reusing a saved address, or completing checkout with stored details. An agent shouldn’t scrape a login form for this. It should send the shopper through an OAuth consent flow and receive a scoped token.

Two standards let an agent discover that flow with no prior setup:

• RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource names the authorization servers that protect your API.
• RFC 8414 Authorization Server Metadata at /.well-known/oauth-authorization-server (or OpenID Connect’s /.well-known/openid-configuration) lists the authorization and token endpoints, scopes and PKCE methods.

The MCP authorization flow relies on exactly this pair. An MCP client that gets a 401 from your agent endpoint follows resource_metadata to RFC 9728, then to the RFC 8414 server metadata. UCP also defines an identity linking capability (dev.ucp.common.identity_linking) for connecting a shopper’s account (UCP overview).

What does the scanner check?

The scanner fetches three paths at the store’s origin with Accept: application/json:

• /.well-known/oauth-protected-resource: valid when it is 2xx JSON with a resource value and an authorization_servers array.
• /.well-known/oauth-authorization-server, falling back to /.well-known/openid-configuration: valid when it is 2xx JSON with issuer and token_endpoint.

Result	When
Pass	Both protected resource metadata and authorization server (or OpenID) metadata are valid.
Partial	Only one of the two is valid.
Fail	Neither is present or valid.

The scanner doesn’t run an OAuth flow or check that the two documents reference each other. It confirms the metadata is discoverable and well-formed.

How do I publish OAuth discovery metadata?

1. Serve protected resource metadata (RFC 9728):

GET /.well-known/oauth-protected-resource
Content-Type: application/json

{
  "resource": "https://store.example/api/ucp/mcp",
  "authorization_servers": ["https://store.example"],
  "scopes_supported": ["orders:read", "checkout:manage"],
  "bearer_methods_supported": ["header"]
}

2. Serve authorization server metadata (RFC 8414) at the issuer:

{
  "issuer": "https://store.example",
  "authorization_endpoint": "https://store.example/oauth/authorize",
  "token_endpoint": "https://store.example/oauth/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["orders:read", "checkout:manage"]
}

The scope names above are examples. Use the scopes your API actually enforces.

3. Point protected endpoints at the metadata. Unauthenticated requests should return:

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

4. Verify: curl -s https://store.example/.well-known/oauth-protected-resource and curl -s https://store.example/.well-known/oauth-authorization-server both return 200 JSON.

If you already run an identity provider (Auth0, Okta, Keycloak and similar), it usually publishes the RFC 8414 or OpenID document for you. You then only add the RFC 9728 document on your store domain.

How to fix it on Medusa

• Medusa’s Auth Module logs customers in (email and password, or third-party providers such as Google) and issues tokens for the Store API.
• Its docs don’t describe it acting as an OAuth authorization server for third-party agents or serving RFC 9728 or RFC 8414 metadata.
• To pass this check, put an OAuth server in front of your agent endpoint and publish both metadata documents from your storefront or a custom API route.

See the Medusa agent-readiness guide.

Sources

• RFC 9728: OAuth 2.0 Protected Resource Metadata
• RFC 8414: OAuth 2.0 Authorization Server Metadata
• MCP specification release 2026-07-28
• UCP specification overview
• Medusa authentication routes