Network Working Group J. Hugo Internet-Draft Independent Intended status: Informational 27 October 2025 Expires: 30 April 2026 API Discovery and Authentication for AI Agents draft-hugo-agent-api-discovery-latest Abstract This document describes a method for AI agents to discover, understand, and authenticate to APIs by composing existing Internet standards. It proposes that the combination of api-catalog for discovery, OpenAPI for capability description and schema discovery, and OAuth 2.0 with its associated metadata specifications for authentication and authorization provides a robust, decentralized alternative to bespoke single-purpose protocols. This approach avoids vendor lock-in, reduces complexity by reusing well-understood technologies, and promotes an open and interoperable ecosystem for AI agent interactions with the existing Web. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/jbg/agent-api-discovery. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 30 April 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction 1.1. Problem Statement 1.2. Solution Approach 2. The Composable Approach 2.1. Discovery with api-catalog 2.1.1. Agent Workflow 2.2. Description with OpenAPI Specification 2.2.1. OpenAPI Document Discovery 2.2.2. Agent Workflow 2.3. Delegated Authorization with OAuth 2.0 2.3.1. Authorization Server Discovery 2.3.2. OAuth 2.0 Grant Types for Agents 2.3.3. Agent Workflow 2.4. Error Handling 3. Conventions and Definitions 4. Security Considerations 5. IANA Considerations 6. References 6.1. Normative References 6.2. Informative References Acknowledgments Author's Address 1. Introduction The proliferation of AI agents necessitates a standardized mechanism for them to interact with the vast landscape of existing APIs. These agents require methods to discover available APIs, understand their functionality, and securely authenticate to them on behalf of a user or system. 1.1. Problem Statement Agent-API interaction faces several challenges: * *Discovery Fragmentation*: No standardized way for agents to discover available APIs across different domains * *Integration Complexity*: Each API requires custom integration code and documentation parsing * *Authentication Inconsistency*: Different APIs use various authentication mechanisms without standardized discovery * *Vendor Lock-in*: Proprietary solutions create dependencies on specific platforms or protocols While solutions like the Model Context Protocol [MCP] have gained popularity, they introduce new protocols and create additional complexity in the ecosystem. These challenges make it difficult for AI agents to dynamically interact with the diverse ecosystem of existing APIs, limiting their effectiveness and creating barriers to interoperability. 1.2. Solution Approach This document proposes a composable approach that leverages existing Internet standards rather than introducing new protocols. By combining api-catalog [RFC9727], OpenAPI [OAS], and OAuth 2.0 [RFC6749] with its discovery mechanisms [RFC8414], this approach provides a robust, decentralized solution that avoids vendor lock-in and reduces complexity. The core capabilities required by an agent can be broken down into three stages: 1. *Discovery*: Finding the right API for a given task 2. *Description*: Understanding the API's endpoints, parameters, and data structures 3. *Delegated Authorization*: Gaining secure, scoped access to the API on behalf of a user This three-stage approach fully addresses the requirements for AI agent-API interaction using well-established Internet standards. 2. The Composable Approach 2.1. Discovery with api-catalog The first stage of agent-API interaction requires the agent to discover which APIs are available for a given task. api-catalog [RFC9727] provides a standardized mechanism for this discovery process. 2.1.1. Agent Workflow An agent implementing this discovery mechanism SHOULD: 1. *Direct Discovery*: Query /.well-known/api-catalog or use link relations to discover APIs available on target domains 2. *Catalog Processing*: Parse the API catalog (in Linkset format [RFC9264]) to extract API endpoints and metadata 3. *Capability Matching*: Match discovered APIs against the agent's task requirements This approach enables agents to systematically discover APIs across the Web without requiring custom discovery protocols or vendor- specific mechanisms. 2.2. Description with OpenAPI Specification Once an agent has discovered an API through the catalog mechanism described in Section 1, it needs to understand the API's capabilities, parameters, and data structures. The OpenAPI Specification [OAS] provides a standardized, machine-readable format for this purpose. 2.2.1. OpenAPI Document Discovery While OpenAPI documents are typically served at conventional endpoints (such as /openapi.json, /swagger.json, or /api-docs), the api-catalog mechanism described in Section 1 can include direct links to OpenAPI specifications. This creates a seamless flow from discovery to description: 1. *Catalog Reference*: The api-catalog includes links to OpenAPI documents for each discovered API 2. *Direct Access*: Agents can fetch OpenAPI documents directly from the URLs provided in the catalog 3. *Conventional Discovery*: As a fallback, agents MAY attempt to discover OpenAPI documents at common endpoints 2.2.2. Agent Workflow An agent implementing this description mechanism SHOULD: 1. *Fetch OpenAPI Document*: Retrieve the OpenAPI specification from the URL provided in the api-catalog 2. *Parse Specification*: Process the document to extract API metadata 3. *Analyze Capabilities*: Match API operations against the agent's task requirements 4. *Plan Integration*: Determine which endpoints and parameters are needed for the task 5. *Prepare Requests*: Structure API calls according to the OpenAPI schema This standardized approach enables agents to dynamically understand and integrate with APIs without requiring custom integration code or vendor-specific documentation formats. 2.3. Delegated Authorization with OAuth 2.0 After discovering and understanding an API's capabilities, an agent must obtain authorization to access protected resources on behalf of a user. The OAuth 2.0 Authorization Framework [RFC6749] provides a standardized mechanism for this delegated authorization, while Authorization Server Metadata [RFC8414] enables agents to discover authorization server capabilities. 2.3.1. Authorization Server Discovery The OAuth 2.0 Authorization Server Metadata specification provides a well-known URI /.well-known/oauth-authorization-server for discovering authorization server configuration. This metadata includes: * Authorization and token endpoint URLs * Supported grant types and response types * Supported scopes and token endpoint authentication methods * Additional capabilities and extensions An agent can discover authorization server capabilities by fetching this metadata, enabling it to determine the appropriate OAuth 2.0 flow and required parameters for obtaining access tokens. 2.3.2. OAuth 2.0 Grant Types for Agents Different OAuth 2.0 grant types are suitable for different agent deployment scenarios: * *Authorization Code Grant*: Suitable for agents with a web-based user interface where users can interact with the authorization server * *Client Credentials Grant*: Appropriate for service-to-service scenarios where the agent acts on behalf of itself rather than a user * *Device Authorization Grant*: Useful for agents running on devices with limited input capabilities The choice of grant type depends on the agent's deployment context and the level of user interaction required. 2.3.3. Agent Workflow An agent implementing delegated authorization SHOULD: 1. *Discover Authorization Server*: Fetch the authorization server metadata from /.well-known/oauth-authorization-server 2. *Determine Grant Type*: Select the appropriate OAuth 2.0 grant type based on the agent's capabilities and deployment context 3. *Initiate Authorization Flow*: Follow the standard OAuth 2.0 flow for the selected grant type to obtain an access token 4. *Use Access Token*: Include the access token in API requests to access protected resources 5. *Handle Token Refresh*: Implement token refresh mechanisms to maintain access when tokens expire This standardized approach enables agents to securely obtain and use access tokens without requiring custom authentication protocols or vendor-specific authorization mechanisms. 2.4. Error Handling Agents implementing this approach SHOULD handle common failure scenarios: * *Discovery Failures*: If /.well-known/api-catalog is unavailable, agents MAY fall back to conventional OpenAPI discovery endpoints * *OpenAPI Parsing Errors*: Malformed or invalid OpenAPI documents SHOULD be handled gracefully with appropriate error reporting * *OAuth Flow Failures*: Authorization failures SHOULD be communicated clearly to users with guidance on resolution * *Protocol Errors*: Implementations SHOULD handle HTTP error responses and invalid protocol responses appropriately 3. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 4. Security Considerations This approach relies on the security models of its constituent parts, primarily OAuth 2.0. Implementers MUST adhere to the security best practices outlined in the relevant specifications, including OAuth 2.0 for Native Apps [RFC8252] and OAuth 2.0 Security Best Current Practice [I-D.ietf-oauth-security-topics]. By leveraging these standards, this approach avoids introducing novel security vulnerabilities that a new protocol might create. 5. IANA Considerations This document has no IANA actions. 6. References 6.1. Normative References [OAS] OpenAPI Initiative, "OpenAPI Specification v3.2.0", 19 September 2025, . [RFC9727] Smith, K., "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs", RFC 9727, DOI 10.17487/RFC9727, June 2025, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . [RFC9264] Wilde, E. and H. Van de Sompel, "Linkset: Media Types and a Link Relation Type for Link Sets", RFC 9264, DOI 10.17487/RFC9264, July 2022, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, . [I-D.ietf-oauth-security-topics] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "OAuth 2.0 Security Best Current Practice", Work in Progress, Internet-Draft, draft-ietf-oauth-security- topics-29, 3 June 2024, . 6.2. Informative References [MCP] "Model Context Protocol", n.d., . Acknowledgments Author's Address Jasper Hugo Independent Email: jasper@jasperhugo.com