WorkOS 发布 auth.md：一种基于 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.

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

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

/ 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.

Agent hits your API, receives

401 Unauthorized

with a

WWW-Authenticate

header pointing to PRM

Agent fetches

/.well-known/oauth-protected-resource

to get the Authorization Server URL

Agent fetches

/.well-known/oauth-authorization-server

and reads the

agent_auth

block: register_uri, claim_uri, revocation_uri, identity_types_supported

WWW-Authenticate: Bearer resource_metadata=”https://api.service.com/.well-known/oauth-protected-resource”

/ 07 Flow 1

Agent Verified Flow

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.

Agent asks user for

consent

to assert identity to your service

Agent requests an audience-specific

ID-JAG

from its provider

Agent POSTs the ID-JAG to your

/agent/auth

endpoint

Your service verifies the signature against the provider’s

JWKS

, validates claims (aud, exp, iat, jti), matches the user, and returns credentials

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.

/ 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

/ 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 <credential>

access_token (ID-JAG flow):

No refresh token is issued. The agent must present a fresh ID-JAG to extend access.

api_key (anonymous or email flow):

Non-expiring by default. Scopes upgrade in place after OTP claim completes.

On any

401 from a previously-working credential

, the agent drops it and restarts discovery from Step 1.

Credentials are scoped, tied to a real user, and independently revocable by the provider or user.

/ 07 Implementation

User Matching, JIT Provisioning and Audit

When credentials are issued, your service resolves which user the registration belongs to. Recommended resolution order:

Delegation record match:

prior (iss, sub) pair. Strongest identifier, what the provider considers stable.

Verified email match:

link to an existing user with the same verified email.

JIT provision:

create a new user per your policy, or reject if manual onboarding is required.

/ 07 Get Started

Minimum Implementation Checklist

Publish

auth.md

at your service root with supported flows, scopes, and endpoint URLs

Publish

/.well-known/oauth-protected-resource

with an agent_auth block

Return

WWW-Authenticate

header on all 401 responses

Implement

/agent/auth

endpoint dispatching on type: anonymous or identity_assertion

For user claimed: implement

/agent/auth/claim

and

/agent/auth/claim/complete

with OTP logic

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:

[email protected]

— AI Research & News

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.