# OAuth discovery documents

> Required for agents to connect to your authenticated API on their own (RFC 8414 / RFC 9728). The fix: publish OAuth discovery documents.

- Source: /checks/oauth-discovery
- Site: AgenticWebScore
- Language: English

---
Required for agents to connect to your authenticated API on their own (RFC 8414 / RFC 9728).

| Property | Value |
| --- | --- |
| Check id | `oauth-discovery` |
| Dimension | Protocol Discovery (25%) |
| Tier | Essential — pool 80 pts |
| Weight inside tier | 2 |
| Impact | High |
| Maturity | Adopted — A ratified standard with real deployment. |
| Conditional | No |
| Publishing skill | `oauth-discovery` |
| Standards | RFC 8414, RFC 9728 |

## What the scanner requests

- `/.well-known/oauth-authorization-server`
- `/.well-known/openid-configuration`
- `/.well-known/oauth-protected-resource`

## What is measured

The scanner GETs /.well-known/oauth-authorization-server, /.well-known/openid-configuration and /.well-known/oauth-protected-resource with no credentials. It passes when one of them returns JSON matching the format for that path: RFC 8414 or OpenID Connect metadata carrying issuer, authorization_endpoint, token_endpoint and response_types_supported, or RFC 9728 protected resource metadata carrying resource and authorization_servers. For protected resource metadata, the scan also requests the RFC 8414 metadata of the same-origin authorization servers it names, up to a published cap. It partially passes when a document is served at a valid path but omits a member required for that format, or when every same-origin authorization server whose metadata the scan requested publishes none with issuer and token_endpoint. An authorization server on another origin, or one whose metadata was not requested, does not change the outcome, and the detail names it as not requested.

## Reproduce it yourself

You do not have to take our word for any of this. Run the same measurement against your own domain:

```bash
DOMAIN=https://your-domain.example
for p in /.well-known/oauth-authorization-server /.well-known/openid-configuration /.well-known/oauth-protected-resource; do printf '%s -> ' "$p"; curl -sS "$DOMAIN$p" | jq -c '{issuer,token_endpoint,resource,authorization_servers}' 2>/dev/null || echo "missing or not JSON"; done
```

## The fix

This is the artifact to ship. It is the complete change, not a description of one.

```json
{
  "resource": "https://api.your-domain.example/",
  "resource_name": "Example API",
  "resource_logo_uri": "https://your-domain.example/logo.png",
  "authorization_servers": ["https://auth.your-domain.example/"],
  "scopes_supported": ["api.read", "api.write"],
  "bearer_methods_supported": ["header"]
}
```

> RFC 9728 metadata only works if authorization_servers resolves to a server that publishes its own RFC 8414 metadata (or OpenID Connect discovery) with issuer and token_endpoint, so ship both documents.

## Standards referenced

- `RFC 8414`
- `RFC 9728`

## Related checks

| Check | Tier | Impact | Same skill |
| --- | --- | --- | --- |
| `mcp-card` — MCP server card | Essential | High | — |
| `openapi` — OpenAPI definition | Essential | High | — |
| `api-catalog` — API catalog | Recommended | Medium | — |
| `agent-skills` — Agent Skills declaration | Recommended | Medium | — |
| `a2a-card` — A2A agent card | Recommended | Medium | — |
| `a2a-signed` — Cryptographically signed agent card | Emerging | Medium | — |
| `auth-md` — /auth.md agent authentication guide | Emerging | Medium | — |
| `webmcp` — WebMCP browser tool declaration | Emerging | Medium | — |