Wiki · Concept · Last reviewed June 25, 2026

OAuth Client ID Metadata Documents

OAuth Client ID Metadata Documents let a client identify itself with an HTTPS URL and host its own client metadata there, giving authorization servers a way to evaluate unfamiliar agent clients without prior registration.

Category: Concept Updated: June 25, 2026 Tags: AI agents, authorization, OAuth, client identity, MCP, audit trails

Definition

OAuth Client ID Metadata Document is an active IETF Internet-Draft, draft-ietf-oauth-client-id-metadata-document-01, by Aaron Parecki and Emelia Smith. The version reviewed here was published on March 2, 2026 and expires on September 3, 2026. It is work in progress, not an RFC.

The draft defines a mechanism where an OAuth client uses an HTTPS URL as its client_id. That URL points to a JSON document containing client metadata such as the client name, redirect URIs, supported grant types, response types, logo URI, client URI, and, where appropriate, public-key information. The authorization server can fetch the document when it encounters the client.

For AI agents, this matters because agent clients and tool surfaces may appear without a prior relationship with every authorization server they need to use. A URL-based client identifier gives the server something to inspect before deciding whether to continue the OAuth flow.

How It Works

The draft restricts the client identifier to a URL with the https scheme and a path component. It forbids fragments, username-password components, and single-dot or double-dot path segments. It recommends short, stable URLs because the client ID may appear in consent and management interfaces.

When an authorization server receives such a client_id, it can fetch the URL to retrieve the client metadata document. The draft says a successful metadata response uses HTTP 200, the metadata document must contain a client_id property matching the document URL by simple string comparison, and the authorization server must not automatically follow redirects while fetching the document.

The metadata values align with the OAuth Dynamic Client Registration metadata registry. The draft also excludes shared-secret client authentication methods from these documents because the client is publishing its own metadata rather than receiving a secret through prior coordination.

Agent Context

The Model Context Protocol makes this more than an abstract OAuth feature. The MCP 2025-11-25 authorization specification says authorization servers and MCP clients should support OAuth Client ID Metadata Documents. It presents the mechanism as the common option when clients and servers have no pre-existing relationship.

In an agent ecosystem, the authorization server may see clients that are desktop apps, web agents, coding agents, browser assistants, or hosted workflow systems. A client metadata document gives the server data to render an approval screen, validate redirect URIs, learn whether the client is public or confidential, and decide which policy applies.

The mechanism does not make an unknown client safe. A polished metadata document can still describe a harmful client. The value is that the authorization server gets a fetchable identity claim and a structured place to apply trust policy instead of treating every unknown agent client as a blank string.

Governance and Safety

The governance value is reciprocal discovery. Protected resource metadata tells the client which authorization server governs a resource; client ID metadata tells the authorization server which client is asking. Together they give agent authorization flows records on both sides of the handshake.

Audit trails should preserve the client ID URL, metadata fetch result, resolved IP class, cache status, metadata digest, redirect URIs, client display fields, authentication method, approval event, authorization server policy decision, and final token issuance. That record matters when a user later asks why a particular agent client was trusted.

The draft's security considerations are practical for agent systems: relationships between redirect URIs and client identity, client authentication, metadata changes, OAuth phishing, server-side request forgery, response-size limits, logo display, client ID domain trust, and supporting both pre-registered and unregistered clients. The server must treat the fetch as security-sensitive infrastructure.

Defense Pattern

Source Discipline

Claims about OAuth Client ID Metadata Documents should identify the exact draft version, client ID URL, metadata fetch behavior, redirect URI policy, authentication method, and cache policy. It should not be confused with OAuth Dynamic Client Registration, OAuth Authorization Server Metadata, OAuth Protected Resource Metadata, or a legal conclusion that a user consented.

Spiralist Reading

Spiralism reads client ID metadata documents as a refusal to let a machine introduce itself with only an opaque string. The client says where it can be found, where it will receive the redirect, and what name it asks the person to recognize.

That introduction is not trust. It is a claim with an address. A serious institution fetches it, checks it, renders it honestly, and remembers why it accepted or rejected the client.

Open Questions

Sources

Return to Wiki