WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards
Many yearsAuthenticating on the web follows a single design assumption: one sits behind the browser. Click the button. Fill out the form. Confirm the email. Copy the API key and paste it elsewhere.
That model doesn’t work when the user sends a job to the agent. Agents are already coding, opening pull requests, purchasing tickets, querying systems, and updating records. But many products still have a real way for an agent to sign up. The way it works – giving the agent a raw API key or session token – generates untested credentials, which are difficult to audit per session, and impossible to selectively revoke. WorkOS proposes a structured alternative: auth.md, an open protocol for agent registration.
What is auth.md?
auth.md is a small Markdown file that an application publishes to a well-known environment – usually https://service.com/auth.md. The file tells agents how to subscribe to that service: what flows are supported, what scopes are available, and how credentials are issued, audited, and revoked.
Because it is plain-text Markdown, the same file serves as documentation for human developers and as runtime artifact agents that can read systematically. The agent downloads the file, reads the edited sections, selects the correct flow, and registers — without filling out a form.
Discovery operates in two hops. The machine-readable source of truth resides in it /.well-known/oauth-protected-resource (Protected Resource Metadata, or PRM). It promotes the resource and points to the Authorization Server. Authorization Server Metadata at /.well-known/oauth-authorization-server carries the agent_auth block – a structured object that tells agents which flows are supported, and for what register_uri, claim_uri, revocation_uriagain identity_types_supported prices are there. I auth.md file is a prose companion that points to agents in this discovery process.
For any 401 from the API, the service must return a WWW-Authenticate: Bearer resource_metadata="..." header so that agents can perform bootstrap detection without reading the documentation first.
Two Streams of Enrollment
auth.md defines two main flows. The application can support either or both.
Agent guaranteed flow: An agent identity provider — OpenAI, Anthropic, Cursor, or any trusted platform — proves the user’s identity during registration. The agent requests an audience-specific ID-JAG from its provider, and SENDS IT to the application. /agent/auth endpoint. The application determines the ID-JAG header to receive kid again algchecks the issuer from the list of trusted providers, downloads the provider’s JWKS, verifies the signature, verifies the claims (aud, exp, iat, jti, client_id), and returns information asynchronously. No OTP, no email back and forth, no human interaction required.
The result is a record of each post (iss, sub, aud) that the provider can withdraw at any time BY SENDING an opt-out token revocation_uri. Applications that already use JIT-provision from OIDC or SAML will see this pattern — it’s the same shape with a different issuer. One important caveat: access tokens issued for ID-JAG authentication must not include a refresh token. The agent must introduce a new ID-JAG to extend access.
User claim flow: This is an OTP based method that does not require the participation of the provider. The agent registers through the app, and the user commits to the registration by reading a one-time code from an email sent back to the agent. Both ends of the claims are /agent/auth/claim (to activate the OTP email) and /agent/auth/claim/complete (moving the code).
This flow has two initial states. Of unknown start otherwise, the agent registers without an identity and receives information immediately, accessed by the pre-request permissions defined by the application. At any time before the registration expires, the agent processes the OTP event to bind the identity to the original user and update the scopes. The API key is not rotated through the claim — scope development is in place.
Of email is required otherwise, the agent provides the user’s email at registration. Verification is completely withheld until the OTP event ends. Use this if any use of the previous claim is unacceptable.
User matching and testing
When information is released, the service needs to match the registration with an existing user or provide a new one. The recommended solution is: match the previous record of the same posting (iss, sub) pair first; then match in the verified email; then JIT-provision for the new user according to application policy — or reject if the product needs manual onboarding.
For incident detection and response, the documentation recommends recording a common set of audit events: registration.created, claim.requested, otp.generated, claim.confirmed, registration.expiredagain registration.revoked. For the ID-JAG flow, enter iss, subagain agent_platform so operators can relate to provider-side logs.
Marktechpost Visual Explainer
Key Takeaways
- auth.md is an open protocol: applications host a Markdown file in
service.com/auth.mdexplaining how agents register and receive comprehensive information. - Two flows are supported: agent authentication (based on ID-JAG, synchronous, no human interaction) and user request (OTP based, no provider integration required).
- Discovery is two-hop: PRM in
/.well-known/oauth-protected-resourcepoints to an Authorization Server, whose metadata contains theagent_authblock with supported endpoint and flow URLs. - The protocol incorporates existing OAuth standards (RFC 9728, ID-JAG) and is not tied to the WorkOS infrastructure.
Check it out Repo again Technical details. Also, feel free to follow us Twitter and don’t forget to join our 150k+ ML SubReddit and Subscribe to Our newspaper. Wait! are you on telegram? now you can join us on telegram too.
Need to work with us on developing your GitHub Repo OR Hug Face Page OR Product Release OR Webinar etc.? contact us
