OAuth Discovery for agents: let the agent find where to authenticate

What it is

OAuth Discovery (RFC 8414) is a JSON document at /.well-known/oauth-authorization-server describing your OAuth server: where the authorization_endpoint and token_endpoint are, and which grant types and scopes are supported. An agent doesn’t need to hardcode these URLs — it discovers them automatically.

Why it matters for AI agents

To call a protected API, an agent must first obtain a token. Without discovery, an integrator hardcodes the OAuth endpoints — brittle and unscalable. With the metadata, the agent (or MCP client) works out how to authenticate on its own. It’s the foundation of autonomous authorization — the OAuth flow in MCP is built on it.

Minimal working example

GET /.well-known/oauth-authorization-server HTTP/1.1

{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/oauth/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "scopes_supported": ["read", "write"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

Right vs wrong

Right	Wrong
Document at /.well-known/oauth-authorization-server	An arbitrary path
issuer matches the base URL	issuer mismatch — clients reject it
Absolute HTTPS endpoints	HTTP or relative paths
Real grant types and scopes listed	Declaring what the server doesn’t support

Common mistakes

• issuer ≠ base URL — breaks the RFC 8414 check; the client refuses.
• HTTP instead of HTTPS in endpoints.
• Incomplete metadata (no token_endpoint) — the flow can’t be assembled.
• Declared scopes/grants don’t actually work.

How to verify

A scan checks for valid metadata. Manually:

curl -s https://example.com/.well-known/oauth-authorization-server | jq .

Expect valid JSON with issuer, authorization_endpoint, token_endpoint.