auth.md: AI Agent Registration on Headless Domains

You ask your agent to register a name on Headless Domains. It finds the site, reads the docs and reaches the next question: how does it get access?

There should be a clear answer. Making an agent piece together a registration flow from a login page and an old API example is asking for trouble.

auth.md gives agents a readable starting point for registration and authentication. Headless Domains publishes its supported path at headlessdomains.com/auth.md. WorkOS has revised the proposal since our May announcement, and we plan to update our implementation. Here's what has changed and how the documented Headless Domains flow works today.

What auth.md does

WorkOS introduced auth.md on May 21, 2026, as an open protocol for agent registration, discoverable through a Markdown file on a service's domain. The file explains how an agent can obtain access; the service implements the endpoints and checks behind those instructions. Read the original WorkOS announcement.

The agent can learn where to register and what identity to present. If a person needs to confirm the request, the file can explain that step too, along with how to use the credential afterward.

The service still decides whether to grant access. The file tells the agent how to ask.

WorkOS's Michael Grinich introduces the idea in the keynote below.

How the proposal has changed since launch

The current WorkOS reference implementation includes examples for both the service receiving a registration and the agent provider supplying identity assertions. Its flows cover provider-backed identity, service-led user authentication and anonymous registration with a later claim.

Registration and credential issuance now have separate endpoints in the reference implementation. In the upstream example, POST /agent/identity establishes the registration, while POST /oauth2/token handles credential issuance. Those are upstream example paths, not instructions to call those routes on Headless Domains.

If you built against the launch version, check these changes in the proposal's changelog before reusing your old requests:

• June 3, v0.2.0: registration and token issuance were separated, with OAuth token and revocation endpoints.
• June 4, v0.4.0: the claim flow moved to a service-owned confirmation page. The agent presents a code and verification URL, then polls for completion. The design borrows from OAuth device authorization but uses its own claim grant.
• June 5, v0.5.0: first-time linking to an existing account gained a confirmation step, alongside checks for recent upstream authentication.
• June 10, v0.6.0: the email-based path became a separate service_auth type using login_hint.

A person can now confirm the claim through the service's own sign-in process, with the agent handling the surrounding requests. The human approval step remains part of the workflow.

A July 23 merged fix addressed a revocation problem in the reference implementation. After access was withdrawn, surviving registration or claim material could still obtain fresh credentials. The fix closes that route. Services using earlier code need to check whether they have incorporated it.

Is auth.md a finalized standard?

As of September 9, 2026, auth.md remains an open protocol proposal with a reference implementation. The changelog ends at v0.6.0, and later changes appear in the repository's commit history. Builders should expect the implementation details to keep changing.

Its provider-backed flow uses Identity Assertion JWT Authorization Grants, or ID-JAGs. That related specification is an active IETF Internet-Draft, not a published RFC. The IETF draft and WorkOS's auth.md project are distinct efforts.

Builders are also asking questions about where the file should be hosted and have submitted a conformance report raising metadata and provider-trust questions. Check how those discussions are resolved before treating a suggestion as part of the protocol.

If you're implementing the protocol, follow the current template and implementation guides. The launch post is useful context, but its request shapes should not be assumed to match today's code.

Headless Domains is preparing an implementation update

We plan to update our implementation for the proposal's newer registration and credential flows. The details below reflect our public documentation on September 9, 2026. Check the live authentication guide and metadata for supported requests as we roll out changes.

Headless Domains' live auth.md documents direct agent provisioning with an API key and a claim code that can later connect the agent to a human account. Human SSO is not required to begin that path.

The live authorization metadata marks anonymous API-key authentication as active and identity assertions as planned. It publishes registration, claim and revocation URLs. The protected-resource metadata lists the resource and supported scopes.

For now, follow the Headless Domains instructions when connecting to our service. Copying the newer WorkOS example endpoints into a Headless Domains request will not make those routes available.

The authentication guide also marks delegated and verified identities backed by PowerLobster/GFAVIP assertions as planned. Those capabilities should be treated as upcoming until our live documentation confirms support.

From registration instructions to a usable name

The currently documented provisioning request is shown below. Check the live guide for changes before using it.

Read it alongside the Headless Domains skill file:

POST https://headlessdomains.com/agent/auth
Content-Type: application/json

{"name":"Example Agent"}

The guide documents an agent_id, api_key and claim_code in the response. Store the credential and claim code securely. Provisioning an agent account is separate from purchasing and registering its domain.

For protected requests using this flow, the guide specifies X-API-Key. In an MPP payment flow, it keeps that header separate from Authorization: Payment, which carries the payment receipt. A receipt establishes payment context, not general authority to change an identity.

Once provisioned, follow the current API contract to search for an available name and complete the applicable checkout. Confirm that registration succeeded before configuring the name's records. An account and a payment receipt aren't confirmation that domain registration has finished.

For payment-specific instructions, use the MPP registration walkthrough. It explains how the agent handles payment once it has reached the service.

Keep auth.md in step with the service

A client should be able to follow auth.md and complete the supported flow. If the file points to an obsolete endpoint, better prose won't help.

When an endpoint or claim process changes, update the file and its supporting metadata together. Explain rejected credentials and human approval steps, and label methods that aren't available yet. The agent needs to know what it can actually do next.

The file also shouldn't tell an agent to put secrets into public records or bypass its operator's rules. Our AI Agent Identity Security guide covers credential handling and enforced permissions. For the broader public identity architecture, see the Agent Identity Stack.

An agent asked to register a name should have a clear route from that request to the supported registration flow. That's what we're working toward with auth.md: instructions the agent can follow, backed by a service that does what they say.

Read Headless Domains auth.md to start the documented registration flow.