What agent-signup.json defines (and why guest-first wins)

1. The problem: agents get stuck at signup walls

An AI shopping agent lands on a product page, decides to buy, hits Checkout, and sees "Create an account to continue." Now what?

A human user copies a password from a password manager and pushes through. An agent has no password manager, no email inbox to poll for a magic link, and no way to solve a hCaptcha. Every signup wall is a hard stop unless the site tells the agent, in a machine-readable file, exactly how signup works and whether it can be skipped.

Right now most sites do not tell agents anything. So the agent guesses. It fails. Or it falls back to a human handoff, which is exactly what your shopper was trying to avoid by using an agent.

2. What agent-signup.json is

agent-signup.json is a small JSON file we place at /.well-known/agent-signup.json. It sits next to agent-checkout.json and llms-pay.md in the same discovery folder (walked through in three discovery files AI shopping agents look for).

It has one required question at the top:

"signup_required": false

If false, the rest of the file explains why the site works guest-first and how post-purchase benefits reach the buyer. If true, the rest of the file explains the flow, the auth methods, and the recovery path.

Version 0.1 of the schema is public at agentfix.pro/schemas/agent-signup-v0.json. It has five required fields (version, site, signup_required, signup_model, authentication_methods) and everything else is optional.

3. The four signup_model options

The signup_model field forces you to pick one honest label:

• guest_first - no account is required to browse, scan, or purchase. Post-purchase benefits (license keys, downloadable assets, dashboard access) are delivered via email or webhook. AgentFix is guest-first.
• required_before_purchase - the shopper must create an account before checkout completes. Common with subscription SaaS and marketplaces.
• required_before_use - the shopper may purchase as a guest but must sign up before actually using the product. Common with cloud tools that need workspace context.
• required_for_features - anonymous access works for the base tier, but signup unlocks specific features (saved history, team sharing, higher quotas).

Pick one. Do not invent a fifth. If your model does not fit, tell us at [email protected] so the schema can grow instead of hand-rolling a custom value.

4. authentication_methods: honest inventory beats vague labels

The authentication_methods array lists exactly which sign-in paths you support. The enum in v0.1:

• email_password
• google_oauth
• github_oauth
• passkey
• magic_link
• sso_saml
• none

Two rules matter here.

First, be exhaustive. If you offer Google OAuth and email+password, list both. Agents may prefer one over the other for reasons the site does not control (some agents can handle magic-link email polling; most cannot).

Second, be honest about what you do not offer. If passkeys are on the roadmap but not shipped, do not list passkey. The agent will attempt the flow, fail, and give up. A missing method is fine. A listed-but-broken method is worse.

Guest-first sites like ours declare "authentication_methods": []. That is a valid, honest inventory.

5. post_purchase_activation: handing off benefits without an account

The most useful field in agent-signup.json for guest-first sites is post_purchase_activation. This block tells the agent what happens after the payment webhook fires.

Ours looks like this:

"post_purchase_activation": {
  "trigger": "creem_webhook_confirms_payment",
  "delivery": {
    "channel": "email",
    "payload": [
      "signed R2 URL (ZIP, 7-day TTL)",
      "license_key (used to activate Chrome extension Pro)",
      "install instructions (INSTALL.md)"
    ]
  },
  "activation_endpoints": {
    "pack_pro_dashboard": "https://agentfix.pro/pack/{scan_id}/manage",
    "chrome_extension": "chrome-extension://.../options.html"
  },
  "help": "[email protected]"
}

An agent reading this knows three things: the webhook is the trigger, benefits arrive by email as a signed download URL plus license key, and there is a dashboard URL template for post-purchase actions. It also knows where to send a human if the agent stalls (help).

If your site sends everything through a dashboard behind a signup wall, your post_purchase_activation will be shorter and more account-shaped. That is fine. What matters is that the description matches what actually happens.

6. identity_privacy: what you tell agents you keep

The identity_privacy block is optional but useful for agents that filter shops by data-handling posture:

"identity_privacy": {
  "pii_collected": ["email (optional, for delivery only)"],
  "pii_retention_days": 365,
  "no_password_storage": true,
  "no_tracking_across_sites": true
}

7. Add it in 15 minutes (static, Next.js, WordPress)

Static site or Nginx: put the file at /public/.well-known/agent-signup.json and add a rewrite rule so it serves as application/json. That is it.

Next.js: create src/app/.well-known/agent-signup.json/route.ts and return the JSON with Content-Type: application/json. See our live file for a working reference: curl https://agentfix.pro/.well-known/agent-signup.json.

WordPress: install the AgentFix Agent Ready plugin (v0.3.0 or later). The admin page has a textarea for agent-signup.json content, and the plugin serves it at the well-known URL with the correct content-type. Empty textarea returns 404 (per the spec's honesty rule) rather than a fabricated file.

After deploy, run our scanner or curl -sI to verify the file returns 200 application/json. Then reference it from llms.txt under a Commerce or Payments section so agents that only fetch llms.txt also find it.

8. Key takeaways