WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards

For years, authentication on the online adopted one design assumption: a human sits behind a browser. Click a button. Fill out a kind. Verify an e mail. Copy an API key and paste it some place else.

That mannequin doesn’t work when the consumer is delegating work to an agent. Agents are already writing code, opening pull requests, triaging tickets, querying methods, and updating information. But most merchandise nonetheless don’t have any possible way for an agent to register. The workaround — giving an agent a uncooked API key or session token — produces credentials which might be unscoped, laborious to audit per session, and unattainable to revoke selectively. WorkOS is proposing a structured various: auth.md, an open protocol for agent registration.

What is auth.md?

auth.md is a small Markdown file an utility publishes at a widely known location — usually https://service.com/auth.md. The file tells brokers the best way to register with that service: which flows are supported, which scopes exist, and the way credentials are issued, audited, and revoked.

Because it’s plain-text Markdown, the identical file works as documentation for human builders and as a runtime artifact brokers can learn programmatically. An agent fetches the file, reads the structured sections, picks the correct circulate, and registers — with no human filling out a kind.

Discovery works in two hops. The machine-readable supply of fact lives at /.well-known/oauth-protected-resource (Protected Resource Metadata, or PRM). It promotes the useful resource and factors on the Authorization Server. The Authorization Server metadata at /.well-known/oauth-authorization-server carries the agent_auth block — the structured object that tells brokers 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 factors brokers towards this discovery path.

On any 401 from the API, the service ought to return a WWW-Authenticate: Bearer resource_metadata="..." header so brokers can bootstrap discovery with out studying documentation first.

The Two Registration Flows

auth.md defines two major flows. An utility can assist both or each.

Agent verified circulate: The agent’s id supplier — OpenAI, Anthropic, Cursor, or any trusted platform — attests to the consumer’s id at registration time. The agent requests an audience-specific ID-JAG from its supplier, then POSTs it to the app’s /agent/auth endpoint. The app decodes the ID-JAG header to get child and alg, appears up the issuer in its trusted suppliers record, fetches the supplier’s JWKS, verifies the signature, validates claims (aud, exp, iat, jti, client_id), and returns credentials synchronously. No OTP, no e mail round-trip, no human interplay required.

The result’s a delegation document per (iss, sub, aud) that the supplier can revoke at any time by POSTing a logout token to the service’s revocation_uri. Apps that already JIT-provision customers from OIDC or SAML will acknowledge this sample — it’s the identical form with a special issuer. One necessary constraint: entry tokens issued from ID-JAG verification should not embody a refresh token. The agent should current a contemporary ID-JAG to increase entry.

User claimed circulate: This is an OTP-based path that requires no agent supplier participation. The agent registers with the app, and the consumer binds the registration by studying a one-time code from an e mail again to the agent. The two declare endpoints are /agent/auth/declare (to set off the OTP e mail) and /agent/auth/declare/full (to submit the code).

This circulate has two beginning shapes. In the nameless begin variant, the agent self-registers with out id and receives a credential instantly, scoped to pre-claim permissions the app defines. At any level earlier than the registration expires, the agent runs the OTP ceremony to bind the credential to an actual consumer and improve scopes. The API key just isn’t rotated on declare — scopes improve in place.

In the e mail required variant, the agent provides a consumer e mail at registration. The credential is withheld totally till the OTP ceremony completes. Use this when any pre-claim utilization is unacceptable.

User Matching and Audit

When credentials are issued, the service must match the registration to an current consumer or provision a brand new one. The advisable decision order is: match on a previous delegation document for a similar (iss, sub) pair first; then match on a verified e mail; then JIT-provision a brand new consumer per the app’s coverage — or reject if the product requires guide onboarding.

For observability and incident response, the docs advocate recording a normal set of audit occasions: registration.created, declare.requested, otp.generated, declare.confirmed, registration.expired, and registration.revoked. For ID-JAG flows, embody 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 area. It tells AI brokers the best way to register on behalf of a consumer: which flows are supported, which scopes exist, and the way credentials are issued, audited, and revoked.

Because it’s plain-text Markdown, the identical file works as documentation for human builders and as a runtime artifact brokers can learn 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 each 401 that factors to the Protected Resource Metadata. The PRM factors 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”

03 / 07 Flow 1

Agent Verified Flow

The agent’s id supplier (OpenAI, Anthropic, Cursor, and many others.) attests to the consumer’s id utilizing an ID-JAG. No human interplay required. Credentials are returned synchronously.

Agent asks consumer for consent to claim id to your service

Agent requests an audience-specific ID-JAG from its supplier

Agent POSTs the ID-JAG to your /agent/auth endpoint

Your service verifies the signature in opposition to the supplier’s JWKS, validates claims (aud, exp, iat, jti), matches the consumer, and returns credentials

Revocation: supplier POSTs a logout token to your revocation_uri. Delegation document is per (iss, sub, aud) tuple.

Trade-off: solely works when the agent’s supplier helps ID-JAG minting. MCP servers and naked LLM API calls usually can’t.

04 / 07 Flow 2

User Claimed Flow

OTP-based registration. No supplier participation required. The agent triggers a code, the consumer reads it again, and the account is claimed. Two beginning shapes:

Anonymous Start

Agent registers with out id
Credential issued instantly at pre-claim scopes
Agent can begin work straight away
OTP ceremony run later to bind an actual consumer
Scopes improve in place, key just isn’t rotated

Email Required

Agent provides consumer e mail at registration
App sends OTP e mail instantly
No credential issued till OTP is verified
Use when any pre-claim entry is unacceptable
Fresh credential issued on /declare/full

POST /agent/auth/declare — set off OTP e mail
POST /agent/auth/declare/full — submit 6-digit code

05 / 07 Credentials

Credential Types and Usage

Your service decides whether or not to difficulty an access_token or an api_key. Both are offered the identical method in API requests.

Authorization: Bearer <credential>

access_token (ID-JAG circulate): No refresh token is issued. The agent should current a contemporary ID-JAG to increase entry.

api_key (nameless or e mail circulate): Non-expiring by default. Scopes improve in place after OTP declare completes.

On any 401 from a previously-working credential, the agent drops it and restarts discovery from Step 1.

Credentials are scoped, tied to an actual consumer, and independently revocable by the supplier or consumer.

06 / 07 Implementation

User Matching, JIT Provisioning and Audit

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

Delegation document match: prior (iss, sub) pair. Strongest identifier, what the supplier considers secure.

Verified e mail match: hyperlink to an current consumer with the identical verified e mail.

JIT provision: create a brand new consumer per your coverage, or reject if guide onboarding is required.

Recommended audit occasions to document:

registration.created
declare.requested
declare.confirmed
registration.expired
registration.revoked

07 / 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 kind: nameless or identity_assertion

For consumer claimed: implement /agent/auth/declare and /agent/auth/declare/full with OTP logic

For agent verified: keep a supplier belief record, confirm ID-JAG signatures in opposition to JWKS, implement jti replay safety

Spec + full auth.md template: github.com/workos/auth.md — Early entry: [email protected]

Key Takeaways

auth.md is an open protocol: apps host a Markdown file at service.com/auth.md describing how brokers register and get scoped credentials.
Two flows are supported: agent verified (ID-JAG-based, synchronous, no human interplay) and consumer claimed (OTP-based, no supplier integration required).
Discovery is two-hop: PRM at /.well-known/oauth-protected-resource factors to the Authorization Server, whose metadata comprises the agent_auth block with endpoint URLs and supported flows.
The protocol composes current OAuth requirements (RFC 9728, ID-JAG) and isn't tied to WorkOS infrastructure.

Check out the Repo and Technical details. Also, be happy to comply with us on Twitter and don’t neglect to affix 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 accomplice with us for selling your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar and many others.? Connect with us

The submit WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards appeared first on MarkTechPost.