The Problem with Agent Authentication

Traditional web authentication assumes a human user interacting with a browser. This model fails for AI agents, which currently rely on raw API keys or session tokens. These credentials are often unscoped, difficult to audit, and impossible to revoke selectively, creating significant security risks as agents begin to perform sensitive tasks like triaging tickets or updating records.

The auth.md Protocol

WorkOS proposes auth.md as a structured, open protocol for agent registration. It functions as both human-readable documentation and a machine-readable runtime artifact. By hosting a Markdown file at a well-known location (e.g., https://service.com/auth.md), developers can programmatically inform agents about supported flows, scopes, and endpoint URLs.

Discovery is handled via a two-hop process:

  1. An API returns a WWW-Authenticate header on 401 errors, pointing to Protected Resource Metadata (PRM) at /.well-known/oauth-protected-resource.
  2. The PRM points to the Authorization Server, which contains an agent_auth block detailing the register_uri, claim_uri, and revocation_uri.

Supported Registration Flows

  • Agent Verified Flow: Leverages identity providers (e.g., OpenAI, Anthropic) to attest to user identity via an ID-JAG (Identity Assertion Authorization Grant). This enables synchronous, human-free registration. Access tokens are short-lived and require a fresh ID-JAG for extension.
  • User Claimed Flow: Uses an OTP-based ceremony for scenarios where provider participation isn't possible. It supports an 'anonymous start' (immediate, limited-scope access followed by a later bind) or an 'email required' start (no access until the OTP is verified). This flow allows for upgrading scopes in place without rotating the underlying API key.

Implementation and Audit

When issuing credentials, services should prioritize matching based on existing delegation records (iss, sub), followed by verified email matching, or JIT provisioning. The protocol recommends tracking specific audit events—such as registration.created, claim.confirmed, and registration.revoked—to ensure observability and incident response capabilities.