For years, authentication on the web followed one design assumption: a human sits behind a browser. Click a button. Fill out a form. Verify an email. Copy an API key and paste it somewhere else.
That model does not work when the user is delegating work to an agent. Agents are already writing code, opening pull requests, triaging tickets, querying systems, and updating records. But most products still have no real way for an agent to register. The workaround — giving an agent a raw API key or session token — produces credentials that are unscoped, hard to audit per session, and impossible to revoke selectively. WorkOS is proposing a structured alternative: auth.md, an open protocol for agent registration.
What is auth.md?
auth.md is a small Markdown file an application publishes at a well-known location — typically https://service.com/auth.md. The file tells agents how to register with that service: which flows are supported, which scopes exist, and how credentials are issued, audited, and revoked.
Because it is plain-text Markdown, the same file works as documentation for human developers and as a runtime artifact agents can read programmatically. An agent fetches the file, reads the structured sections, picks the right flow, and registers — without a human filling out a form.
Discovery works in two hops. The machine-readable source of truth lives at /.well-known/oauth-protected-resource (Protected Resource Metadata, or PRM). It promotes the resource and points at the Authorization Server. The Authorization Server metadata at /.well-known/oauth-authorization-server carries the agent_auth block — the structured object that tells agents which flows are supported, and what the register_uri, claim_uri, revocation_uri, and identity_types_supported values are. The auth.md file is the prose companion that points agents toward this discovery path.
On any 401 from the API, the service should return a WWW-Authenticate: Bearer resource_metadata="..." header so agents can bootstrap discovery without reading documentation first.
The Two Registration Flows
auth.md defines two primary flows. An application can support either or both.
Agent verified flow: The agent’s identity provider — OpenAI, Anthropic, Cursor, or any trusted platform — attests to 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 get 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 required.
The result is a delegation record per (iss, sub, aud) that the provider can revoke at any time by POSTing a logout token to the service’s revocation_uri. Apps that already JIT-provision users from OIDC or SAML will recognize this pattern — it is the same shape with a different issuer. One important constraint: 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 participation. The agent registers with the app, and the user binds the registration by reading 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: apps host a Markdown file at
service.com/auth.mddescribing how agents register and get scoped credentials. - Two flows are supported: agent verified (ID-JAG-based, synchronous, no human interaction) and user claimed (OTP-based, no provider integration required).
- Discovery is two-hop: PRM at
/.well-known/oauth-protected-resourcepoints to the Authorization Server, whose metadata contains theagent_authblock with endpoint URLs and supported flows. - The protocol composes existing OAuth standards (RFC 9728, ID-JAG) and is not tied to WorkOS infrastructure.
Check out 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.
Need to partner with us for promoting your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar etc.? Connect with us
