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

> OAuth discovery metadata lets an AI agent find out, without custom setup, how to get a shopper's permission to act on their account. Serve /.well-known/oauth-protected-resource (RFC 9728) and /.well-known/oauth-authorization-server (RFC 8414) or openid-configuration.

- Source: https://is-agentic-storefront.com/checks/oauth-discovery
- Updated: 2026-10-15
- Category: Agentic commerce (15% of score)
- Impact: Medium
- Spec: [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)
- Scanner check: OAuth discovery metadata for agent sign-in (RFC 9728 / RFC 8414)

## 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](https://datatracker.ietf.org/doc/html/rfc9728) Protected Resource Metadata** at `/.well-known/oauth-protected-resource` names the authorization servers that protect your API.
- **[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) 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](https://blog.modelcontextprotocol.io/posts/2026-07-28/) relies on exactly this pair. An MCP client that gets a 401 from your [agent endpoint](https://is-agentic-storefront.com/checks/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](https://ucp.dev/2026-08-25/specification/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):

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

```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:

```json
{
  "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
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](https://docs.medusajs.com/resources/commerce-modules/auth/authentication-route) logs customers in (email and password, or third-party providers such as [Google](https://docs.medusajs.com/resources/commerce-modules/auth/auth-providers/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](https://docs.medusajs.com/learn/fundamentals/api-routes).

See the [Medusa agent-readiness guide](https://is-agentic-storefront.com/guides/medusa-agent-readiness).

## Sources

- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
- [RFC 8414: OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)
- [MCP specification release 2026-07-28](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
- [UCP specification overview](https://ucp.dev/2026-08-25/specification/overview/)
- [Medusa authentication routes](https://docs.medusajs.com/resources/commerce-modules/auth/authentication-route)

## Frequently asked questions

### What is /.well-known/oauth-protected-resource?

It is OAuth 2.0 Protected Resource Metadata, defined in RFC 9728. It tells a client which authorization servers issue tokens for your API, and MCP clients use it to start sign-in.

### Do I need OAuth for AI agents to buy from my store?

Not for guest checkout. OAuth matters when an agent acts on a signed-in shopper's account, such as reading orders, using saved addresses or checking out with stored details.

### Is openid-configuration enough?

It covers the authorization server half. For a full pass the scanner also needs /.well-known/oauth-protected-resource, which links your API to that server.

## Run your store on a platform built for agentic commerce

Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.

### Deploy on Medusa Cloud

Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.

- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Foauth-discovery)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Foauth-discovery)

### Storefront skills for coding agents

Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.

```bash
npx skills add medusajs/medusa-agent-skills
```

[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)

---

Scan your store for free at https://is-agentic-storefront.com/