API, OAuth, and OIDC Discovery for AI Agents: A Practical Guide

Modern AI agents do more than read web pages — they authenticate with services, call APIs, and take actions on behalf of users. For this to work reliably at scale, agents need to discover what your API can do and how to authenticate with it, without requiring a human to configure each connection manually. This guide covers the four standards that make that automatic discovery possible.

OpenAPI: Your API's Machine-Readable Contract

The OpenAPI Specification (formerly Swagger) is a JSON or YAML document that fully describes a REST API — its endpoints, request parameters, response shapes, and authentication methods. When published at a predictable URL like /openapi.json and declared via a Link header (rel="service-desc"), it becomes the primary way AI agents learn what your API can do.

A minimal OpenAPI document that an agent can act on looks like this:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Acme Search API",
    "version": "1.0.0",
    "description": "Search Acme's product catalogue and documentation."
  },
  "servers": [{ "url": "https://api.acme.com/v1" }],
  "paths": {
    "/search": {
      "get": {
        "operationId": "searchCatalogue",
        "summary": "Search the product catalogue",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Search query"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchResults" }
              }
            }
          }
        }
      }
    }
  }
}

The operationId field is particularly important for agents — it is used as the function name when the LLM decides which API call to make. Keep it descriptive and unique.

ai-plugin.json — The ChatGPT Plugin Format

OpenAI's ChatGPT plugin specification introduced /.well-known/ai-plugin.json as a higher-level wrapper around an OpenAPI spec. While ChatGPT plugins as a product have evolved, the manifest format has been adopted broadly and is now used as a general AI agent discovery file:

{
  "schema_version": "v1",
  "name_for_human": "Acme Search",
  "name_for_model": "acme_search",
  "description_for_human": "Search Acme products and documentation.",
  "description_for_model": "Use this to search Acme's product catalogue and knowledge base. Useful when the user asks about Acme products, pricing, or support topics.",
  "auth": { "type": "none" },
  "api": {
    "type": "openapi",
    "url": "https://acme.com/openapi.json"
  },
  "logo_url": "https://acme.com/logo.png",
  "contact_email": "api@acme.com",
  "legal_info_url": "https://acme.com/terms"
}

The description_for_model field is critical — it tells the AI agent when to use your API and what kinds of queries it is suited for. A well-written description dramatically increases the chances of an agent choosing your tool over alternatives.

OAuth Authorization Server Metadata — RFC 8414

When your API requires OAuth authentication, agents need to know where to get tokens. RFC 8414 defines a JSON metadata document that authorization servers publish at /.well-known/oauth-authorization-server. An agent fetches this and immediately has everything it needs to complete an OAuth flow:

{
  "issuer": "https://auth.acme.com",
  "authorization_endpoint": "https://auth.acme.com/oauth/authorize",
  "token_endpoint": "https://auth.acme.com/oauth/token",
  "jwks_uri": "https://auth.acme.com/.well-known/jwks.json",
  "scopes_supported": ["read", "write", "admin"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials"],
  "code_challenge_methods_supported": ["S256"]
}

Without this metadata document, agents must be hard-coded with your token endpoint URL — a fragile approach that breaks when you change providers or URLs. With it, the entire auth configuration is self-describing and discoverable.

OIDC Discovery — OpenID Connect Provider Metadata

OpenID Connect (OIDC) extends OAuth 2.0 with an identity layer. For services that use OIDC for user authentication, the provider publishes a discovery document at /.well-known/openid-configuration. This is a superset of the OAuth AS metadata and adds OIDC-specific fields:

{
  "issuer": "https://auth.acme.com",
  "authorization_endpoint": "https://auth.acme.com/oauth/authorize",
  "token_endpoint": "https://auth.acme.com/oauth/token",
  "userinfo_endpoint": "https://auth.acme.com/userinfo",
  "jwks_uri": "https://auth.acme.com/.well-known/jwks.json",
  "id_token_signing_alg_values_supported": ["RS256"],
  "subject_types_supported": ["public"],
  "claims_supported": ["sub", "email", "name", "picture"]
}

Any standards-compliant OIDC library or AI agent can auto-configure an authentication flow from this document. If you are using a hosted identity provider (Auth0, Okta, Supabase Auth, Clerk), this document is almost certainly already published — check your provider's documentation for the URL.

OAuth Protected Resource Metadata — RFC 9728

The newest piece of the puzzle is RFC 9728, which defines metadata published by the resource server (your API) rather than the authorization server. At /.well-known/oauth-protected-resource, your API declares which authorization server an agent should use to obtain a token:

{
  "resource": "https://api.acme.com",
  "authorization_servers": ["https://auth.acme.com"],
  "scopes_supported": ["read", "write"],
  "bearer_methods_supported": ["header"]
}

This solves a bootstrapping problem: an agent might know about your API endpoint but not know which authorization server issues tokens for it. The protected resource metadata provides that link, completing the chain from API discovery to authenticated access.

The Full Agentic Discovery Chain

These standards fit together into a predictable flow that a well-configured agent can execute automatically, without human intervention:

1. Agent makes a HEAD request to your domain — reads the Link header
2. Discovers /openapi.json via rel="service-desc" — reads the API schema
3. Sees auth requirement in the OpenAPI securitySchemes
4. Fetches /.well-known/oauth-protected-resource to find the auth server
5. Fetches /.well-known/oauth-authorization-server (or openid-configuration) to get token endpoints
6. Completes the OAuth flow — obtains a scoped access token
7. Calls your API with the token — takes action on behalf of the user