OAuth Discovery Endpoint: What It Is and How to Add It

Learn how to add an OAuth 2.0 authorization server metadata document at /.well-known/oauth-authorization-server so AI agents can authenticate with your API automatically.

What is OAuth discovery?

OAuth 2.0 Authorization Server Metadata (RFC 8414) is a standard JSON document at /.well-known/oauth-authorization-server that describes how to authenticate with your API — endpoints, supported grant types, scopes, and PKCE support. It's what AI agents and OAuth clients read to authenticate without hardcoded configuration.

Why AI agents need it

When an MCP-compatible AI agent wants to call your API on behalf of a user, it needs to know your authorization endpoint, token endpoint, and supported scopes. Without a discovery document, agents either fail or require manual configuration — both poor outcomes for adoption.

Minimal discovery document

Here is the minimum valid OAuth discovery document. Replace the URLs and scopes with your own:

/.well-known/oauth-authorization-server

{
  "issuer": "https://yourdomain.com",
  "authorization_endpoint": "https://yourdomain.com/oauth/authorize",
  "token_endpoint": "https://yourdomain.com/oauth/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["read", "write"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "none"]
}

In Next.js: serve as a static file

Place the document in your public directory. Next.js will serve it automatically at the correct URL path:

Terminal

mkdir -p public/.well-known
# Create the file at:
# public/.well-known/oauth-authorization-server

Or serve it as an API route

If you generate the values dynamically, use a Next.js route handler:

src/app/.well-known/oauth-authorization-server/route.ts

export async function GET() {
  return Response.json({
    issuer: "https://yourdomain.com",
    authorization_endpoint: "https://yourdomain.com/oauth/authorize",
    token_endpoint: "https://yourdomain.com/oauth/token",
    response_types_supported: ["code"],
    grant_types_supported: ["authorization_code", "refresh_token"],
    code_challenge_methods_supported: ["S256"],
    scopes_supported: ["read", "write"],
  });
}

Verify the endpoint

Once deployed, confirm the document is served correctly:

Terminal

curl -s https://yourdomain.com/.well-known/oauth-authorization-server | jq .
# Should return your JSON document with 200 status

PKCE is required for public clients

AI agents acting as public clients (no client secret) must use PKCE (Proof Key for Code Exchange). Ensure your authorization server supports code_challenge_method=S256 and include it in code_challenge_methods_supported.