WorkOS 推出 auth.md 协议，为 AI 智能体提供标准化注册流程。这是一个部署在应用域名的 Markdown 文件，告知智能体支持哪些注册流程、请求哪些权限范围以及如何获取绑定真实用户的凭证，无需人工填写表单。该协议建立在现有 OAuth 标准之上。
原文 · 未翻译
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.
WorkOS 推出 auth.md 协议，为 AI 智能体提供标准化注册流程。这是一个部署在应用域名的 Markdown 文件，告知智能体支持哪些注册流程、请求哪些权限范围以及如何获取绑定真实用户的凭证，无需人工填写表单。该协议建立在现有 OAuth 标准之上。
原文 · 保持原样，未翻译
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.
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
auth.md — Implementation Guide
Open Protocol
01 / 07 Overview
What Is auth.md?
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.
Because it is plain-text Markdown, the same file works as documentation for human developers and as a runtime artifact agents can read programmatically.
Open Protocol
No WorkOS Account Required
OAuth-Based
https://workos.com/auth-md
02 / 07 Discovery
How Agents Find Your Endpoints
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 block with all endpoint URLs.
1
Agent hits your API, receives 401 Unauthorized with a WWW-Authenticate header pointing to PRM
2
Agent fetches /.well-known/oauth-protected-resource to get the Authorization Server URL
3
Agent fetches /.well-known/oauth-authorization-server and reads the agent_auth block: register_uri, claim_uri, revocation_uri, identity_types_supported
The agent’s identity provider (OpenAI, Anthropic, Cursor, etc.) attests to the user’s identity using an ID-JAG. No human interaction required. Credentials are returned synchronously.
1
Agent asks user for consent to assert identity to your service
2
Agent requests an audience-specific ID-JAG from its provider
3
Agent POSTs the ID-JAG to your /agent/auth endpoint
4
Your service verifies the signature against the provider’s JWKS, validates claims (aud, exp, iat, jti), matches the user, and returns credentials
5
Revocation: provider POSTs a logout token to your revocation_uri. Delegation record is per (iss, sub, aud) tuple.
Trade-off: only works when the agent’s provider supports ID-JAG minting. MCP servers and bare LLM API calls typically cannot.
04 / 07 Flow 2
User Claimed Flow
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:
Anonymous Start
Agent registers without identity
Credential issued immediately at pre-claim scopes
Agent can start work right away
OTP ceremony run later to bind a real user
Scopes upgrade in place, key is not rotated
Email Required
Agent supplies user email at registration
App sends OTP email immediately
No credential issued until OTP is verified
Use when any pre-claim access is unacceptable
Fresh credential issued on /claim/complete
POST /agent/auth/claim — trigger OTP email POST /agent/auth/claim/complete — submit 6-digit code
05 / 07 Credentials
Credential Types and Usage
Your service decides whether to issue an access_token or an api_key. Both are presented the same way in API requests.
Authorization: Bearer
01
access_token (ID-JAG flow): No refresh token is issued. The agent must present a fresh ID-JAG to extend access.
02
api_key (anonymous or email flow): Non-expiring by default. Scopes upgrade in place after OTP claim completes.
03
On any 401 from a previously-working credential, the agent drops it and restarts discovery from Step 1.
04
Credentials are scoped, tied to a real user, and independently revocable by the provider or user.
06 / 07 Implementation
User Matching, JIT Provisioning and Audit
When credentials are issued, your service resolves which user the registration belongs to. Recommended resolution order:
1
Delegation record match: prior (iss, sub) pair. Strongest identifier, what the provider considers stable.
2
Verified email match: link to an existing user with the same verified email.
3
JIT provision: create a new user per your policy, or reject if manual onboarding is required.
Recommended audit events to record:
registration.created
claim.requested
claim.confirmed
registration.expired
registration.revoked
07 / 07 Get Started
Minimum Implementation Checklist
01
Publish auth.md at your service root with supported flows, scopes, and endpoint URLs
02
Publish /.well-known/oauth-protected-resource with an agent_auth block
03
Return WWW-Authenticate header on all 401 responses
04
Implement /agent/auth endpoint dispatching on type: anonymous or identity_assertion
05
For user claimed: implement /agent/auth/claim and /agent/auth/claim/complete with OTP logic
06
For agent verified: maintain a provider trust list, verify ID-JAG signatures against JWKS, implement jti replay protection
Spec + full auth.md template: github.com/workos/auth.md — Early access: authmd@workos.com
← Prev
Next →
Marktechpost — AI Research & News
marktechpost.com
Key Takeaways
auth.md is an open protocol: apps host a Markdown file at service.com/auth.md describing 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-resource points to the Authorization Server, whose metadata contains the agent_auth block 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
The post WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards appeared first on MarkTechPost.
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
auth.md — Implementation Guide
Open Protocol
01 / 07 Overview
What Is auth.md?
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.
Because it is plain-text Markdown, the same file works as documentation for human developers and as a runtime artifact agents can read programmatically.
Open Protocol
No WorkOS Account Required
OAuth-Based
https://workos.com/auth-md
02 / 07 Discovery
How Agents Find Your Endpoints
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 block with all endpoint URLs.
1
Agent hits your API, receives 401 Unauthorized with a WWW-Authenticate header pointing to PRM
2
Agent fetches /.well-known/oauth-protected-resource to get the Authorization Server URL
3
Agent fetches /.well-known/oauth-authorization-server and reads the agent_auth block: register_uri, claim_uri, revocation_uri, identity_types_supported
The agent’s identity provider (OpenAI, Anthropic, Cursor, etc.) attests to the user’s identity using an ID-JAG. No human interaction required. Credentials are returned synchronously.
1
Agent asks user for consent to assert identity to your service
2
Agent requests an audience-specific ID-JAG from its provider
3
Agent POSTs the ID-JAG to your /agent/auth endpoint
4
Your service verifies the signature against the provider’s JWKS, validates claims (aud, exp, iat, jti), matches the user, and returns credentials
5
Revocation: provider POSTs a logout token to your revocation_uri. Delegation record is per (iss, sub, aud) tuple.
Trade-off: only works when the agent’s provider supports ID-JAG minting. MCP servers and bare LLM API calls typically cannot.
04 / 07 Flow 2
User Claimed Flow
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:
Anonymous Start
Agent registers without identity
Credential issued immediately at pre-claim scopes
Agent can start work right away
OTP ceremony run later to bind a real user
Scopes upgrade in place, key is not rotated
Email Required
Agent supplies user email at registration
App sends OTP email immediately
No credential issued until OTP is verified
Use when any pre-claim access is unacceptable
Fresh credential issued on /claim/complete
POST /agent/auth/claim — trigger OTP email POST /agent/auth/claim/complete — submit 6-digit code
05 / 07 Credentials
Credential Types and Usage
Your service decides whether to issue an access_token or an api_key. Both are presented the same way in API requests.
Authorization: Bearer
01
access_token (ID-JAG flow): No refresh token is issued. The agent must present a fresh ID-JAG to extend access.
02
api_key (anonymous or email flow): Non-expiring by default. Scopes upgrade in place after OTP claim completes.
03
On any 401 from a previously-working credential, the agent drops it and restarts discovery from Step 1.
04
Credentials are scoped, tied to a real user, and independently revocable by the provider or user.
06 / 07 Implementation
User Matching, JIT Provisioning and Audit
When credentials are issued, your service resolves which user the registration belongs to. Recommended resolution order:
1
Delegation record match: prior (iss, sub) pair. Strongest identifier, what the provider considers stable.
2
Verified email match: link to an existing user with the same verified email.
3
JIT provision: create a new user per your policy, or reject if manual onboarding is required.
Recommended audit events to record:
registration.created
claim.requested
claim.confirmed
registration.expired
registration.revoked
07 / 07 Get Started
Minimum Implementation Checklist
01
Publish auth.md at your service root with supported flows, scopes, and endpoint URLs
02
Publish /.well-known/oauth-protected-resource with an agent_auth block
03
Return WWW-Authenticate header on all 401 responses
04
Implement /agent/auth endpoint dispatching on type: anonymous or identity_assertion
05
For user claimed: implement /agent/auth/claim and /agent/auth/claim/complete with OTP logic
06
For agent verified: maintain a provider trust list, verify ID-JAG signatures against JWKS, implement jti replay protection
Spec + full auth.md template: github.com/workos/auth.md — Early access: authmd@workos.com
← Prev
Next →
Marktechpost — AI Research & News
marktechpost.com
Key Takeaways
auth.md is an open protocol: apps host a Markdown file at service.com/auth.md describing 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-resource points to the Authorization Server, whose metadata contains the agent_auth block 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
The post WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards appeared first on MarkTechPost.