OAuth Discovery Generator

Create OAuth discovery metadata for authorization servers and protected APIs. Generate standards-oriented JSON, review its configuration and publish it at the correct well-known URL.

1. Choose the metadata document

Select Authorization server if you issue OAuth tokens. Select Protected resource if your API accepts tokens from an authorization server.

2. Authorization server details

The exact HTTPS identity of your authorization server.
Where interactive authorization starts.
Where supported token exchanges occur.
Optional. Public verification keys only.
Optional. Include only if implemented.
Optional. Include only if supported.
Optional. Include only if supported.
Optional. Used by OpenID Connect implementations.
Optional. Human-readable service documentation.

Grant types supported

Response types supported

Token endpoint client authentication

PKCE challenge methods

Comma-separated list of actual scope names. Leave empty if you do not advertise scopes.

2. Protected resource details

HTTPS identifier of the protected resource.
Comma-separated issuer URLs.
Optional public keys for the protected resource.
Optional resource documentation.
Optional scopes understood by the protected resource.

All generation and validation take place in this request. The tool does not store credentials or create a working OAuth deployment.

3. Generated JSON

Choose the document type and enter your real OAuth endpoint information. The generated JSON, publication URL, warnings, and export options will appear here.

Publication checklist

  1. Use your deployed HTTPS issuer or resource identifier.
  2. List only real endpoints and supported capabilities.
  3. Publish the JSON at the generated well-known URL.
  4. Serve HTTP 200 with Content-Type: application/json.
  5. Check that the published identifier matches exactly.
  6. Test your actual authorization flow and security controls separately.

What is OAuth discovery?

OAuth discovery is a standard way for applications and AI agents to learn how a service handles authorization. Instead of asking every integrator to manually configure endpoint addresses, a service can publish public JSON metadata that identifies its endpoints, supported authorization flows and relevant capabilities.

There are two closely related documents. RFC 8414 explains discovery for an authorization server that issues tokens. RFC 9728 explains discovery for protected resources such as APIs. Many integrations use both.

Why OAuth discovery matters for AI optimisation

AI search is not limited to finding pages. Some AI systems also connect to tools and services, subject to user authorization and platform support. A compatible client may need to discover which authorization server protects an API, which endpoint accepts authorization requests and how token exchanges work. Standard metadata reduces manual integration work and makes these configurations easier to locate.

This belongs to technical AI Discoverability, particularly for APIs and agent-enabled applications. It is different from optimizing article structure or achieving a citation in an AI-generated answer. Publishing OAuth metadata does not improve search rankings by itself, grant an agent access or bypass user consent.

Authorization server versus protected resource

QuestionAuthorization server metadataProtected resource metadata
What does it describe?Server issuing OAuth tokensAPI or other resource accepting tokens
SpecificationRFC 8414RFC 9728
Main required identifierissuerresource
Typical fieldsAuthorization and token endpoints, grant types, response typesAuthorization server issuers and supported scopes
Default publication path/.well-known/oauth-authorization-server/.well-known/oauth-protected-resource

How discovery works in practice

  1. An API advertises the resource it represents and may identify supported authorization servers.
  2. A compatible client obtains the authorization server's metadata and verifies the issuer identifier.
  3. The client learns where supported authorization flows begin and where tokens may be issued.
  4. Authorization and token exchange take place using the actual server implementation and its security requirements.
  5. The client presents authorized tokens to the protected API, which still verifies permissions and enforces access.

Metadata assists discovery. It does not implement any of those security controls.

How to use the OAuth Discovery Generator

Step 1: Choose the correct document

If you operate the server that issues OAuth tokens, choose Authorization server. If you operate an API that accepts OAuth access tokens, choose Protected resource. A service can have both documents.

Step 2: Enter existing configuration

Use the exact identifiers and HTTPS endpoints from your deployed application. Select only actual grants, response types, authentication methods and scopes. Avoid publishing aspirational capabilities that the server cannot support.

Step 3: Review and export

Generate JSON, address the validation warnings, copy the output or download it. The publication URL is calculated according to the relevant specification, including issuer or resource path segments where applicable.

Step 4: Publish and verify

Deploy the JSON at the expected well-known URL using the correct content type. Confirm that it is accessible and that the identifier inside the document matches the identifier used to derive the discovery URL. Validate real OAuth flows separately.

Important fields explained

Issuer and resource identifiers

The issuer identifies the authorization server, while the resource identifier identifies an API or protected service. Their exact values matter because clients use them to connect discovered metadata to the intended server and prevent confusion between services.

Endpoints and grants

The authorization endpoint handles interactive authorization where applicable. The token endpoint supports token issuance and exchange for supported grants. Grant types indicate which OAuth flows the server actually offers, while response types specify the supported authorization response formats.

Scopes, authentication and JWKS

Scopes indicate available permission names. Token endpoint authentication methods explain how supported clients authenticate themselves. A public JWKS endpoint can expose verification keys but must not publish private signing material.

Security and common mistakes

Publishing discovery metadata is a configuration step, not proof that the service is secure. Use HTTPS, avoid exposing secrets, verify tokens and audiences, enforce scopes, protect endpoints, and check the precise issuer or resource identity. A missing metadata file may make integrations less convenient, but a misleading file can be worse because it directs clients to capabilities that do not exist.

For new implementations, favor current security guidance such as OAuth 2.0 Security Best Current Practice (RFC 9700) and PKCE (RFC 7636). The generator highlights legacy flows for this reason.

How OAuth discovery relates to other AI readiness tools

OAuth metadata matters most when an AI system needs to connect to an authorized service. For a broader assessment, use the Site Agent Readiness Checker. To inspect other emerging agent protocols, use the Emerging Protocols Checker. If your service publishes a catalog of agent capabilities, use the Agentic Resource Discovery Checker. Explore all AI search optimisation tools.

Official references

Frequently asked questions

OAuth discovery publishes machine-readable JSON metadata so compatible clients can locate an authorization server, token endpoint or the authorization servers used by a protected API.

RFC 8414 describes an OAuth authorization server, including its issuer and endpoints. RFC 9728 describes a protected resource, such as an API, and can identify its authorization servers.

Teams operating OAuth authorization servers, protected APIs, SaaS integrations and agent-connected services. A normal informational website without protected APIs usually does not need OAuth discovery.

No. It can improve technical interoperability when an agent needs authorized access to an API. It is not a published Google or AI answer engine ranking signal and does not guarantee citations.

Publish JSON at the RFC 8414 well-known location derived from the issuer, such as https://example.com/.well-known/oauth-authorization-server. Issuers with path segments require those segments after the well-known suffix.

Use the RFC 9728 well-known location derived from the resource identifier, such as https://api.example.com/.well-known/oauth-protected-resource.

The issuer is the exact HTTPS identifier of your authorization server. OAuth clients must compare the discovered issuer to the expected issuer. It must not contain a query or fragment.

Their requirements depend on supported grant types. An authorization endpoint is not needed for grants that never use one. A token endpoint is not needed when only the implicit grant is supported.

RFC 8414 defines response_types_supported as required. For client credentials only servers, the reported RFC 8414 erratum discusses the ambiguity; this generator flags the situation for review rather than inventing a response type.

No. Metadata must contain only public configuration. Never include client secrets, private signing keys, access tokens, passwords or credentials.

It identifies a public JSON Web Key Set used for verifying relevant signed tokens or metadata. The endpoint must use HTTPS and must not expose private signing keys.

Scopes describe permission names that the server may grant, such as read:reports. They do not themselves issue permissions. Only advertise scopes your real server supports.

Grant types define ways clients may obtain access tokens, such as authorization_code, refresh_token and client_credentials. Choose only flows actually implemented on the authorization server.

It identifies supported ways a client authenticates at the token endpoint, such as client_secret_basic, private_key_jwt or none for appropriately designed public clients.

No. It creates standards-oriented discovery metadata, not the authorization endpoints, token issuing logic, consent screens or security controls.

Compatible clients may use published metadata to configure integrations. Actual behavior depends on client support, authorization policy, user consent and secure implementation.

Public authorization metadata and the issuer use HTTPS to protect discovery integrity and reduce impersonation risks. RFC 8414 requires an HTTPS issuer.

Review the checks and warnings, copy or download the JSON, deploy it with application/json content type and confirm that the public URL responds with HTTP 200 and the expected issuer or resource identifier.

Protected Resource Metadata can help OAuth-capable MCP clients discover authorization servers for a protected resource. It does not create an MCP server or implement OAuth by itself.

No. API authorization, token verification, audience and scope enforcement, HTTPS configuration and appropriate threat protections are required separately.