For years web authentication has assumed a human behind a browser: click a button, fill a form, verify an email, copy an API key and paste it elsewhere. That model breaks down when the user delegates work to an AI agent. Agents are already writing code, opening pull requests, triaging tickets, querying systems and updating records, yet most services still have no native way for an agent to register. The common workaround—handing the agent a raw API key or session token—creates credentials that are unscoped, hard to audit per session and impossible to revoke selectively.
The auth.md protocol solves this by providing an open, plain‑text description of how agents can register and receive scoped, auditable credentials. A service publishes a small markdown file at a well‑known location (for example service.com/auth.md) that lists the supported registration flows, available scopes and the endpoints used to issue, audit and revoke access. Because the file is plain text it works both as developer documentation and as a machine‑readable artifact that agents can fetch and interpret automatically.
Discovery is built on existing OAuth mechanisms. When an API call returns 401 the service includes a WWW‑Authenticate header pointing to the Protected Resource Metadata at /.well‑known/oauth‑protected‑resource. That document points to the Authorization Server metadata at /.well‑known/oauth‑authorization‑server, which contains an agent_auth block with the exact URLs for registration, claim and revocation, as well as the identity types the server accepts.
Two registration flows are defined. The agent verified flow relies on the agent’s identity provider (OpenAI, Anthropic, Cursor, etc.) to issue an ID‑JAG attestation. The agent posts that token to the service’s /agent/auth endpoint; the service verifies the signature against the provider’s JWKS, validates claims and returns credentials synchronously. No OTP, no email round‑trip and no human interaction are required. Access tokens issued this way do not include refresh tokens—the agent must present a fresh ID‑JAG to extend access.
The user claimed flow is OTP‑based and needs no provider participation. The agent can start anonymously, receive a credential with limited pre‑claim scopes and later upgrade it by having the user read a one‑time code sent to email. Alternatively, the agent can supply an email up front and withhold any credential until the OTP ceremony completes.
When credentials are issued the service matches the registration to an existing user by checking prior delegation records, then verified email, then falling back to JIT provisioning or rejection per policy. Standard audit events—registration created, claim requested, OTP generated, claim confirmed, registration expired and registration revoked—should be recorded, with iss, sub and agent_platform included for ID‑JAG flows to correlate with provider logs.
Implementation checklist: publish auth.md, publish the protected resource and authorization server metadata, return WWW‑Authenticate on every 401, implement the /agent/auth endpoint handling both anonymous and identity_assertion types, add the OTP claim endpoints for the user claimed flow, maintain a trusted provider list and verify ID‑JAG signatures with replay protection.
This approach gives agents scoped, independently revocable credentials, provides clear audit trails and eliminates the need for insecure API key sharing.
#AI #Product #Auth #Security #DevOps #OpenSource
