For years, web authentication has operated under a single assumption: a human is sitting behind the browser. Click a button. Complete a form. Confirm an email. Copy an API key and paste it somewhere else.
That approach breaks down when the user is handing tasks off to an AI agent. Agents are already writing code, opening pull requests, triaging tickets, querying systems, and updating records. Yet most products still lack a proper way for an agent to register. The common workaround — handing an agent a raw API key or session token — creates credentials that are overly broad, difficult to audit on a per-session basis, and impossible to revoke selectively. WorkOS is introducing a structured solution: auth.md, an open protocol for agent registration.
What is auth.md?
auth.md is a lightweight Markdown file that an application hosts at a well-known location — typically https://service.com/auth.md. The file instructs agents on how to register with that service: which authentication flows are available, which scopes are defined, and how credentials are issued, audited, and revoked.
Because it is plain-text Markdown, the same file serves double duty — as documentation for human developers and as a machine-readable artifact that agents can parse at runtime. An agent fetches the file, reads the structured sections, selects the appropriate flow, and registers — all without a human filling out a form.
Discovery happens in two steps. The machine-readable source of truth lives at /.well-known/oauth-protected-resource (Protected Resource Metadata, or PRM). It advertises the resource and points to the Authorization Server. The Authorization Server metadata at /.well-known/oauth-authorization-server contains the agent_auth block — the structured object that tells agents which flows are supported, along with the register_uri, claim_uri, revocation_uri, and identity_types_supported values. The auth.md file acts as the human-readable companion that guides agents toward this discovery path.
On any 401 response from the API, the service should return a WWW-Authenticate: Bearer resource_metadata="..." header so agents can bootstrap discovery without needing to consult documentation first.
The Two Registration Flows
auth.md defines two primary flows. An application can support one or both.
Agent verified flow: The agent’s identity provider — OpenAI, Anthropic, Cursor, or any trusted platform — vouches for the user’s identity at registration time. The agent requests an audience-specific ID-JAG from its provider, then POSTs it to the app’s /agent/auth endpoint. The app decodes the ID-JAG header to extract kid and alg, looks up the issuer in its trusted providers list, fetches the provider’s JWKS, verifies the signature, validates claims (aud, exp, iat, jti, client_id), and returns credentials synchronously. No OTP, no email round-trip, no human interaction needed.
The outcome is a delegation record per (iss, sub, aud) that the provider can revoke at any time by sending a logout token to the service’s revocation_uri. Apps that already JIT-provision users from OIDC or SAML will recognize this pattern — it follows the same structure with a different issuer. One important restriction: access tokens issued from ID-JAG verification must not include a refresh token. The agent must present a fresh ID-JAG to extend access.
User claimed flow: This is an OTP-based path that requires no agent provider involvement. The agent registers with the app, and the user binds the registration by relaying a one-time code from an email back to the agent. The two claim endpoints are /agent/auth/claim (to trigger the OTP email) and /agent/auth/claim/complete (to submit the code).
This flow has two starting shapes. In the anonymous start variant, the agent self-registers without identity and receives a credential immediately, scoped to pre-claim permissions the app defines. At any point before the registration expires, the agent runs the OTP ceremony to bind the credential to a real user and upgrade scopes. The API key is not rotated on claim — scopes upgrade in place.
In the email required variant, the agent supplies a user email at registration. The credential is withheld entirely until the OTP ceremony completes. Use this when any pre-claim usage is unacceptable.
User Matching and Audit
When credentials are issued, the service needs to match the registration to an existing user or provision a new one. The recommended resolution order is: match on a prior delegation record for the same (iss, sub) pair first; then match on a verified email; then JIT-provision a new user per the app’s policy — or reject if the product requires manual onboarding.
For observability and incident response, the docs recommend recording a standard set of audit events: registration.created, claim.requested, otp.generated, claim.confirmed, registration.expired, and registration.revoked. For ID-JAG flows, include iss, sub, and agent_platform so operators can correlate with provider-side logs.
Marktechpost’s Visual Explainer
Key Takeaways
- auth.md is an open protocol: applications host a Markdown file at
service.com/auth.mdthat explains how agents register and obtain scoped credentials. - Two flows are available: agent verified (based on ID-JAG, synchronous, no human involvement) and user claimed (based on OTP, no provider integration needed).
- Discovery follows a two-hop process: the PRM at
/.well-known/oauth-protected-resourcedirects to the Authorization Server, whose metadata includes theagent_authblock containing endpoint URLs and supported flows. - The protocol builds on existing OAuth standards (RFC 9728, ID-JAG) and does not depend on WorkOS infrastructure.
Explore the Repo and Technical details. Also, feel free to follow us on Twitter and don’t forget to join our 150k+ ML SubReddit and subscribe to our Newsletter. Wait — are you on Telegram? Now you can join us on Telegram as well.
Looking to partner with us to promote your GitHub repo, Hugging Face page, product release, webinar, or more? Connect with us
