WorkOS auth.md — agentic registration, and where it fits OpenAlice

NAO asked (TG): "full deep research on WorkOS auth.md — evaluate how it helps us and how & where best to integrate it into our ecosystem." This is the grounded eval + the integration map + phased recommendation. Implementation owners (if greenlit) = Norbert (openalice-auth / Alice-core) + Tycho (Embed) + ATLAS (platform); this doc is the strategy/map, not an impl spec.

>

Method: 5 parallel readers — spec deep-dive (read the actual repo), the agent-auth standards landscape, WorkOS strategy/traction, our-stack fit (Atlas + repos), and sovereignty+security+decision. Sources cited inline; unverified items flagged. Complements [[competitor-dossier-auth-identity-2026-06-21]] (which predates auth.md) + [[mcp]].

TL;DR for OpenAlice strategists

1. auth.md = "/sign-up for agents." An open (MIT) protocol — authored by WorkOS but explicitly not tied to WorkOS infra — that lets an AI agent register/authenticate a *user* with a service on the user's behalf, with no sign-up form. A service hosts a /auth.md markdown "skill manifest" + an agent_auth block in its OAuth metadata; the agent discovers it (401 → RFC 9728 → RFC 8414) and follows a recipe: discover → register → (claim) → exchange → use → revoke. It's pure composition of mature OAuth RFCs + the IETF draft ID-JAG — not a new token system.
2. It's dual-sided for us, and both sides serve our roadmap: (A) PUBLISH — our products (Embed, Alice's API) host an auth.md so external agents (Claude/GPT/Cursor) onboard users into us without a form → distribution in the agent era; (B) CONSUME — Alice-the-agent reads others' auth.md to act for a user → the agentic capability ([[product-line-gtm]] AGI substrate).
3. It fits our EU-sovereign wedge unusually well. The protocol is 100% implementable in openalice-auth on Hetzner-DE with zero WorkOS calls; WorkOS's own AuthKit is US-only / CLOUD-Act-exposed. So: adopt the open protocol, never the vendor.
4. But it's young. 5 weeks old (created 2026‑05‑20, v0.6.0), ~506 stars, ~9 launch adopters; ID-JAG is IETF draft-04, "Intended RFC status: None." Forrester (Identiverse 2026): all agentic-identity standards are "<12 months old, WIP, or not final." → adopt the low-risk roles now/soon, defer the speculative one.
5. Recommendation (phased): (0) publish a minimal auth.md for Embed/Alice (cheap agent-native positioning win) — when openalice-auth next gets attention; (1) build Alice-as-consumer (the real prize — Alice onboards users into external services); (2) DEFER openalice-auth-as-ID-JAG-issuer (the "identity broker" play) until the draft matures + GDPR analysis. Avoid AuthKit. Sequenced behind Embed-cash, but #0 is a small, on-brand bet.

1. What auth.md actually is

A service that wants to be "agent-registerable" publishes two things: a human/agent-readable `/auth.md` (a procedural Markdown recipe — "You are an agent. This service supports agentic registration: discover → register → (claim if needed) → exchange → call API → handle revocation. Follow the steps in order.") and a machine-readable `agent_auth` block inside its standard OAuth metadata.

Discovery (two-hop, all standard): the agent hits a 401 whose WWW-Authenticate carries resource_metadata=<URL> → fetches /.well-known/oauth-protected-resource (RFC 9728) → fetches /.well-known/oauth-authorization-server (RFC 8414), which carries the lone extension: the agent_auth object (skill, identity_endpoint, claim_endpoint, events_endpoint, supported identity types + assertion formats). Everything else is vanilla OAuth.

Three registration flows:

• Agent-Verified (ID-JAG) — the agent's identity provider mints a signed, audience-specific ID-JAG JWT vouching for the user (email_verified:true, fresh auth_time, ~5-min exp); the service verifies it against the provider's JWKS and returns a token. No human in the loop. (ID-JAG = IETF draft draft-ietf-oauth-identity-assertion-authz-grant.)
• User-Claimed (service_auth) — the agent passes an email hint; the service starts a claim ceremony (RFC 8628 device-flow shape): a 6-digit `user_code` + verification_uri; the agent shows them to the user, the user signs in at the service and confirms; the agent polls the token endpoint. "The code travels you → user, not service → user."
• Anonymous — a pre-claim, limited-scope token immediately; the user can claim ownership later (which revokes all pre-claim tokens and widens scope).

Token model: scoped, short-lived (access_token ~1h), user-tied, revocable — and no refresh token (you re-exchange the intermediate service-signed assertion via RFC 7523 JWT-bearer). Two revocation layers: credential (RFC 7009) + whole-registration via Security Event Token push (RFC 8417/8935). It composes RFC 9728, 8414, 7523, 7009, 8628, 8417/8935, 7517 + ID-JAG — nothing proprietary in the crypto.

2. WorkOS's play, and how "open" it really is

WorkOS is a $2B auth unicorn ($100M Series C, Mar 2026; ~$30M ARR; ~95 staff) whose customers are the AI labs themselves — OpenAI, Anthropic, xAI, Cursor, Perplexity, Vercel. auth.md (launched ~May 23 2026) is a textbook standard-then-funnel: author the open spec, become the reference, route adopters to AuthKit (their one-click impl; early-access; US-only; free <1M MAU then $2,500/M). Week-1 adopters: Cloudflare, Resend, Firecrawl, Monday.com, NanoGPT, Zuplo (~9). Community shorthand: "auth.md = /sign-up for agents."

Is it genuinely open? Mostly yes. The file format, the agent_auth block, all three flows, the claim ceremony, and the SET revocation channel are MIT spec — implementable with zero WorkOS account. The only WorkOS-branded wire elements are two string URNs (urn:workos:agent-auth:grant-type:claim and a schemas.workos.com/...revoked event), which are just identifiers for endpoints you build yourself. The honest caveats: no independent governance body (WorkOS controls the repo, feedback by email), and the load-bearing ID-JAG is a draft (expires Nov 2026, not on the RFC track).

3. Where it sits in the agent-auth race

By mid-2026 the space has six complementary layers, and auth.md fills a gap none of the others touch:

auth.md and MCP are complementary, not competing: MCP = agent↔tool access; auth.md = agent registers a user↔service. They even share RFC 9728 as the discovery layer — an agent can use auth.md to acquire a user-scoped credential, then use it when calling an MCP-discovered tool. The vendor platforms (Descope/Arcade/Stytch/Clerk/Auth0) are US SaaS — study their patterns (per-user OAuth, just-in-time consent, token vaulting, step-up auth) but don't depend on them. Forrester's verdict: OAuth 2.1+OIDC is the only mature, deployed layer; everything agent-specific is still solidifying.

4. How it maps to OpenAlice

Our stack today (Atlas + repo-grounded): openalice-auth is the central Rust SSO — mints/verifies JWTs (HS256 default, RS256 opt-in), /internal/* + X-Internal-Secret M2M, MFA/TOTP, device pairing, and `/.well-known/jwks.json` (RFC 7517) already present. It is an OAuth consumer (YouTube/Twitch connectors), not yet an OAuth authorization server. Missing for auth.md: the RFC 8414 AS-metadata endpoint, the agent_auth endpoints (/agent/identity, /agent/identity/claim, the JWT-bearer token_endpoint, the SET events_endpoint), and email + tid claims in the JWT struct (the latter already noted as deferred in middleware.rs). Grade C/77 (roadmap + code_health are the weak axes). Embed is A/90. (Honesty flag: the dossier credits `openalice-auth` with SAML 2.0 + SCIM 2.0, but the reader did not find that in local `src/` — dossier may be ahead of code; verify before quoting.) The AliceToolProvider MCP bridge (brick 8a.1) was reverted — but per Norbert (2026-06-30) that ceiling was specific to claude-as-tool-user (a legal CLI can't do client-side tool-exec); it is not a blocker for the auth.md-consumer / scoped-token-storage case (a different code path). consult_advisor is a stub today.

The three roles, mapped to our products:

5. Sovereignty & security

• Sovereignty — a clean fit. The protocol is fully implementable in `openalice-auth` on Hetzner Germany with no WorkOS call (the surface is ~3 HTTP endpoints + 2 .well-known docs + 1 markdown file + a jti replay store + a provider allowlist — all standard libs). WorkOS AuthKit is US-only / CLOUD-Act-exposed per their DPA. So adopting the open standard strengthens our EU-sovereign wedge ([[competitor-dossier-auth-identity-2026-06-21]]); using their SaaS would break it. Never route identity data through WorkOS.
• Security — the real risks. In ID-JAG, consent sits with the agent provider, not the service; the service's only lever is the provider allowlist → a rogue-but-trusted provider is the worst case. Claim-ceremony phishing (a rogue agent showing a spoofed verification_uri) is not mitigated by the spec — the implementer must (e.g., show the canonical URL in a branded element). Mitigations the spec does give: scoped + short-lived + revocable tokens, jti replay store, auth_time max-age, and email-binds-the-claim (only the intended signed-in user can complete it).
• GDPR — the tiering (grounded, 2026-06-30). Inbound assertions (US provider → our EU service) aren't themselves a "restricted transfer" (GDPR restricts data leaving the EU). The real issues: (i) anything we send back to a US provider (revocation SETs, "user joined X" events) = EU→US restricted transfer needing DPF or SCCs + a Schrems-II Transfer Impact Assessment; (ii) CLOUD-Act exposure — a US provider in the identity path can be compelled regardless of data location; our durable moat = CLOUD-Act-vs-GDPR-Art.48, which adequacy/DPF does not cure. On adequacy: the EU-US DPF was UPHELD (General Court, 3-Sep-2025, Latombe dismissed) so DPF-certified US providers are a valid transfer basis today — but it's on appeal (CJEU Case C-703/25 P, pending) and its two predecessors (Safe Harbor, Privacy Shield) were both struck down, so don't anchor the sovereign story on DPF surviving. The clean tiering: user-claimed / anonymous = GDPR-clean + fully EU-sovereign (no US provider in the loop) → the default; ID-JAG from a US provider = an opt-in *convenience* tier (consent Art. 6 / 49(1)(a) + DPF or SCC + transparency Art. 13/14 + email-only minimization) — never the sovereign default; ID-JAG from an EU / our-own IdP = sovereign-clean. Lawful basis is satisfied by the agent-consent step (the provider obtains user consent before asserting), but we must still capture/log it + inform the user (Art. 13/14).
• Maturity, nuanced (corrected 2026-06-30). The auth.md wrapper is ~5 weeks old. But its core — ID-JAG — is more mature than "draft" implies: adopted by the IETF OAuth WG (Sept 2025), folded into the MCP authorization spec (Nov 2025), and already minted by the major agent providers (Anthropic / OpenAI / Cursor). The agent-verified path is real and shipping, not theoretical. The genuinely soft parts: the auth.md wrapper's governance (WorkOS-controlled, no IANA registry for its 2 URNs) and whether a rival registration convention emerges (Microsoft Entra Agent ID, Google).

6. Recommendation

Strategic frame: as the web's front-end shifts to agents, being agent-registerable becomes the new "being on Google." auth.md is an open, EU-sovereign-implementable, dual-sided bet that rides our existing openalice-auth JWT infra and serves both Embed distribution and Alice's agentic capability. That alignment is rare — but the immaturity says adopt the low-risk roles, defer the speculative one.

• Phase 0 — PUBLISH a minimal auth.md (low cost, on-brand). When `openalice-auth` next gets attention. Host /auth.md + RFC 9728/8414 metadata + the user-claimed + anonymous flows (skip ID-JAG acceptance → no allowlist needed). ~1 sprint; the markdown+metadata alone is hours. Makes Embed/Alice agent-onboardable and gives a genuine "EU-sovereign, agent-native auth" positioning line. Honest gate: only matters once agents are actually onboarding users to us, and Embed is the #1 cash gate — so this is a fast-follow / cheap symbolic win, not a drop-everything.
• Phase 1 — Alice as CONSUMER (the real prize). 1–2 months out. A built-in tool that discovers + runs external services' auth.md (the user-claimed flow as the primary path — Alice shows the code+URL in Telegram/Embed and polls). This is the autonomous-agent capability; it lands in agents-tools + the (to-be-revived) MCP bridge. Skip ID-JAG consumption (needs us on others' provider allowlists — unrealistic now).
• ID-JAG — three roles, only ONE is genuinely "later" (corrected 2026-06-30). I was too coarse calling "ID-JAG" a single deferred thing. Split it: (a) ACCEPT ID-JAGs (publish side) — do this in Phase 1, NOT defer. Embed/Alice accept agent-verified assertions from trusted providers (Anthropic/OpenAI/Cursor — who already mint them, it's in MCP) → zero-friction onboarding from exactly the platforms users live in. Gate: a curated provider allowlist + the GDPR tiering (offer it as the opt-in convenience tier; user-claimed stays the sovereign default). (b) ISSUE ID-JAGs *internally (`openalice-auth` vouches for users across our own services) — low-risk, no external dependency or cross-border PII; fine alongside Phase 1. **(c) ISSUE ID-JAGs externally* (us as a *public* agent-IdP — "Sign in with Alice"; external services accept our assertions) — this** is the genuine defer: it only pays off once external services allowlist us (ecosystem standing we don't have yet). ~3–4 weeks of backend when it's time; build (c) later, after (a)/(b) prove the muscle.
• AVOID WorkOS AuthKit and every US vendor platform (CLOUD Act). Implement on pure RFCs; treat the 2 WorkOS URNs as endpoints we own (or substitute IETF-standard ones where possible).

Verdict: Adopt the protocol, not the product — it's a cheap, sovereignty-positive, agent-native bet whose two payoffs (Embed agent-onboarding + Alice acting for users) are exactly our roadmap. Start with publish + consume on standard RFCs; defer the ID-JAG issuer. This is a recommendation for NAO to route to Norbert (`openalice-auth`/Alice) + Tycho (Embed) — not for me to build.

Sources & honesty notes

• Spec facts are read from the workos/auth.md repo (AUTH.md, README, agent-services/providers READMEs, CHANGELOG) + workos.com/auth-md; protocol mechanics verified against the cited RFCs + the ID-JAG draft.
• Unverified / flagged: ID-JAG is draft-04 ("Intended RFC status: None") — spec may shift; openalice-auth SAML/SCIM is dossier-claimed but unconfirmed in local code; AuthKit's exact feature set is early-access/undisclosed; auth.md adoption beyond the ~9 launch partners is unconfirmed; whether Anthropic/OpenAI ship ID-JAG provider minting is unconfirmed; openalice-tenants provisioning model not read.
• Related: [[competitor-dossier-auth-identity-2026-06-21]] · [[competitive-intel-index-2026-06-21]] · [[mcp]] · [[tool-use-function-calling]] · [[ai-native-companies-the-one-human-playbook-2026-06-25]] · [[product-line-gtm]].