{"id":971,"date":"2026-05-25T15:38:15","date_gmt":"2026-05-25T07:38:15","guid":{"rendered":"https:\/\/connectword.dpdns.org\/?p=971"},"modified":"2026-05-25T15:38:15","modified_gmt":"2026-05-25T07:38:15","slug":"workos-releases-auth-md-an-open-agent-registration-protocol-built-on-oauth-standards","status":"publish","type":"post","link":"https:\/\/connectword.dpdns.org\/?p=971","title":{"rendered":"WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards"},"content":{"rendered":"

For years<\/em>, 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.<\/p>\n

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 \u2014 giving an agent a raw API key or session token \u2014 produces credentials that are unscoped, hard to audit per session, and impossible to revoke selectively. WorkOS is proposing a structured alternative: auth.md<\/a>, an open protocol for agent registration.<\/strong><\/p>\n

What is auth.md?<\/strong><\/h2>\n

auth.md is a small Markdown file an application publishes at a well-known location \u2014 typically https:\/\/service.com\/auth.md<\/code>. 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.<\/p>\n

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 \u2014 without a human filling out a form.<\/p>\n

Discovery works in two hops. The machine-readable source of truth lives at \/.well-known\/oauth-protected-resource<\/code> (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<\/code> carries the agent_auth<\/code> block \u2014 the structured object that tells agents which flows are supported, and what the register_uri<\/code>, claim_uri<\/code>, revocation_uri<\/code>, and identity_types_supported<\/code> values are. The auth.md<\/code> file is the prose companion that points agents toward this discovery path.<\/p>\n

On any 401 from the API, the service should return a WWW-Authenticate: Bearer resource_metadata=\"...\"<\/code> header so agents can bootstrap discovery without reading documentation first.<\/p>\n

The Two Registration Flows<\/strong><\/h2>\n

auth.md defines two primary flows. An application can support either or both.<\/p>\n

Agent verified flow<\/strong>: The agent\u2019s identity provider \u2014 OpenAI, Anthropic, Cursor, or any trusted platform \u2014 attests to the user\u2019s identity at registration time. The agent requests an audience-specific ID-JAG<\/a> from its provider, then POSTs it to the app\u2019s \/agent\/auth<\/code> endpoint. The app decodes the ID-JAG header to get kid<\/code> and alg<\/code>, looks up the issuer in its trusted providers list, fetches the provider\u2019s JWKS, verifies the signature, validates claims (aud<\/code>, exp<\/code>, iat<\/code>, jti<\/code>, client_id<\/code>), and returns credentials synchronously. No OTP, no email round-trip, no human interaction required.<\/p>\n

The result is a delegation record per (iss, sub, aud)<\/code> that the provider can revoke at any time by POSTing a logout token to the service\u2019s revocation_uri<\/code>. Apps that already JIT-provision users from OIDC or SAML will recognize this pattern \u2014 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.<\/p>\n

User claimed flow<\/strong>: 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<\/code> (to trigger the OTP email) and \/agent\/auth\/claim\/complete<\/code> (to submit the code).<\/p>\n

This flow has two starting shapes. In the anonymous start<\/strong> 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 \u2014 scopes upgrade in place.<\/p>\n

In the email required<\/strong> 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.<\/p>\n

User Matching and Audit<\/strong><\/h2>\n

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)<\/code> pair first; then match on a verified email; then JIT-provision a new user per the app\u2019s policy \u2014 or reject if the product requires manual onboarding.<\/p>\n

For observability and incident response, the docs recommend recording a standard set of audit events: registration.created<\/code>, claim.requested<\/code>, otp.generated<\/code>, claim.confirmed<\/code>, registration.expired<\/code>, and registration.revoked<\/code>. For ID-JAG flows, include iss<\/code>, sub<\/code>, and agent_platform<\/code> so operators can correlate with provider-side logs.<\/p>\n

Marktechpost\u2019s Visual Explainer<\/strong><\/h2>\n
\n
\n
auth.md \u2014 Implementation Guide<\/div>\n
Open Protocol<\/div>\n<\/div>\n
\n
\n

<\/p>\n

\n
01<\/span> \/ 07 \u00a0\u00a0Overview<\/div>\n
What Is auth.md?<\/div>\n

<\/span><\/p>\n

auth.md is a small Markdown file your app publishes at its domain. It tells AI agents how to register on behalf of a user: which flows are supported, which scopes exist, and how credentials are issued, audited, and revoked.<\/div>\n
Because it is plain-text Markdown, the same file works as documentation for human developers and as a runtime artifact agents can read programmatically.<\/div>\n
\n
Open Protocol<\/div>\n
No WorkOS Account Required<\/div>\n
OAuth-Based<\/div>\n<\/div>\n
https:\/\/workos.com\/auth-md<\/div>\n<\/div>\n

<\/p>\n

\n
02<\/span> \/ 07 \u00a0\u00a0Discovery<\/div>\n
How Agents Find Your Endpoints<\/div>\n

<\/span><\/p>\n

Discovery works in two hops. Your API returns a header on every 401 that points to the Protected Resource Metadata. The PRM points to the Authorization Server, which carries the agent_auth<\/strong> block with all endpoint URLs.<\/div>\n
\n
\n
1<\/div>\n
Agent hits your API, receives 401 Unauthorized<\/strong> with a WWW-Authenticate<\/strong> header pointing to PRM<\/div>\n<\/div>\n
\n
2<\/div>\n
Agent fetches \/.well-known\/oauth-protected-resource<\/strong> to get the Authorization Server URL<\/div>\n<\/div>\n
\n
3<\/div>\n
Agent fetches \/.well-known\/oauth-authorization-server<\/strong> and reads the agent_auth<\/strong> block: register_uri, claim_uri, revocation_uri, identity_types_supported<\/div>\n<\/div>\n<\/div>\n
WWW-Authenticate: Bearer resource_metadata=\u201dhttps:\/\/api.service.com\/.well-known\/oauth-protected-resource\u201d<\/div>\n<\/div>\n

<\/p>\n

\n
03<\/span> \/ 07 \u00a0\u00a0Flow 1<\/div>\n
Agent Verified Flow<\/div>\n

<\/span><\/p>\n

The agent\u2019s identity provider (OpenAI, Anthropic, Cursor, etc.) attests to the user\u2019s identity using an ID-JAG<\/strong>. No human interaction required. Credentials are returned synchronously.<\/div>\n
\n
\n
1<\/div>\n
Agent asks user for consent<\/strong> to assert identity to your service<\/div>\n<\/div>\n
\n
2<\/div>\n
Agent requests an audience-specific ID-JAG<\/strong> from its provider<\/div>\n<\/div>\n
\n
3<\/div>\n
Agent POSTs the ID-JAG to your \/agent\/auth<\/strong> endpoint<\/div>\n<\/div>\n
\n
4<\/div>\n
Your service verifies the signature against the provider\u2019s JWKS<\/strong>, validates claims (aud, exp, iat, jti), matches the user, and returns credentials<\/div>\n<\/div>\n
\n
5<\/div>\n
Revocation: provider POSTs a logout token<\/strong> to your revocation_uri. Delegation record is per (iss, sub, aud)<\/strong> tuple.<\/div>\n<\/div>\n<\/div>\n
Trade-off: only works when the agent\u2019s provider supports ID-JAG minting. MCP servers and bare LLM API calls typically cannot.<\/div>\n<\/div>\n

<\/p>\n

\n
04<\/span> \/ 07 \u00a0\u00a0Flow 2<\/div>\n
User Claimed Flow<\/div>\n

<\/span><\/p>\n

OTP-based registration. No provider participation required. The agent triggers a code, the user reads it back, and the account is claimed. Two starting shapes:<\/div>\n
\n
\n
Anonymous Start<\/div>\n
\n