Proposal: origin fields for anonymous-start registration limits

[sergeliatko]

Summary

I would like to propose adding a small origin model to the anonymous-start registration flow in auth.md.

The important scope is narrow: this proposal is only about the anonymous flow where an agent can receive a usable pre-claim credential before a human has taken ownership. It is not a proposal for identity_assertion with ID-JAG, identity_assertion with verified_email, agent-provider registration, provider-driven revocation, or any other verified identity flow.

The reason is simple: SaaS services usually need to give new users some free value before asking them to pay, approve, or fully commit. That can be a trial period, credits, a limited number of tool calls, read-only access, storage, compute, or some other service-specific allowance.

With the anonymous auth.md flow, an agent can start that flow before a human is present. That is useful for product-led onboarding. The agent can try the service, see whether it is useful, and later ask a human to claim the account.

The same thing creates an abuse-control problem. Software can create accounts and consume free resources much faster than a human. If the protocol makes anonymous account creation easy, services need a common way to meter that free access without relying only on blunt IP limits.

Scope

The current README describes three registration flows on /agent/auth: ID-JAG identity assertion, verified-email identity assertion, and anonymous registration with OTP claim.

This issue only concerns the third flow: anonymous registration with OTP claim.

That flow is different because the service immediately creates an agent principal, issues a scoped API key, returns a claim token, and lets the agent operate with pre-claim scopes. The service may later upgrade the same key after a human claim ceremony.

The other two flows already have a stronger identity axis. In the ID-JAG path, a trusted agent provider asserts identity. In the verified-email path, the service sends email before issuing the credential. Those flows may still need rate limits, but I do not think this proposal should change their request shape.

Current anonymous auth.md shape

Today the anonymous request is intentionally small:

{
  "type": "anonymous",
  "requested_credential_type": "api_key"
}

That is enough for the service to create an anonymous agent account, return a credential, expose pre-claim permissions, and provide the claim information that lets a human take ownership later.

What it does not provide is a standard way to describe where the anonymous registration came from.

That missing origin becomes important once the service grants real trial value to the anonymous account.

What I think is missing

A service may want to limit anonymous registrations by more than one axis.

A simple IP cap is useful, but it is not enough. Many honest users can share one IP address, and abusive traffic can rotate IP addresses.

A simple final-account cap is not enough either. If every anonymous registration creates a new final account or workspace, the cap resets with every new account.

There is also an isolation problem. Two similar agents on the same machine, or two threads of the same app, can produce identical request metadata. If the service derives the final account directly from that metadata, two different credentials can end up pointing at the same unclaimed account.

So I think the anonymous flow needs to distinguish between two things:

• a shared origin key that can be used for abuse limits
• the final account or workspace ID that the issued credential can access

Those should not be the same thing.

Proposed anonymous origin values

The existing anonymous request could stay valid, with three optional caller-supplied fields added to the anonymous request shape:

{
  "type": "anonymous",
  "requested_credential_type": "api_key",
  "channel": "application",
  "source": "application-a",
  "user": "123"
}

channel describes what kind of path brought the request. For example: application, agent, browser, system, or unknown.

source identifies the app, agent, browser, or system inside that channel.

user identifies the source-local user or subject when that is known. If it is not known, the service can treat it as anonymous.

There is also a fourth origin value, which I would call connection, but it should not be submitted by the agent. The service should derive it from trusted request metadata: the observed IP address, a trusted edge header, a gateway value, a device signal, or another connection signal the service controls.

That connection value should be hashed before it is stored.

How the limits would work

The service can normalize the caller-supplied anonymous origin values and combine them with a hashed service-derived connection key:

channel:source:user:connectionKey

Example:

application:application-a:123:hash:ip-203-0-113-10

This is the shared limit key. It is used for caps and analysis. It is not the final account ID.

The service can then allocate a suffix under that shared key:

shared limit key: application:application-a:123:hash:ip-203-0-113-10
suffix: 0

The final account ID should still be generated in the service's normal format. For example, a SaaS app may use UUIDv7 or another regular database/account ID format:

final account id: 018f6c83-4c4a-7000-8000-000000000001

If the same anonymous origin registers again, it keeps the same shared limit key, receives the next suffix, and receives another generated account ID:

shared limit key: application:application-a:123:hash:ip-203-0-113-10
suffix: 1
final account id: 018f6c83-4c4a-7000-8000-000000000002

Both accounts count against the same anonymous origin, but the credentials do not point at the same unclaimed account.

What this enables

With this shape, a service can limit anonymous-start registrations by:

• channel
• source
• user
• connection key
• shared limit key
• total count

It can also apply different policies before and after claim.

Before claim, an anonymous agent might get narrow pre-claim permissions and a small credit grant.

After a human claims the account, the service might grant post-claim permissions, more credits, a longer lifetime, billing access, or access to more sensitive tools.

Claimed and expired accounts should free capacity for concurrent-unclaimed caps.

The public error should not reveal which limit was hit. A safe response can tell the agent to claim an existing account or retry later.

Privacy and storage

Services should store the normalized origin fields, the hashed connection key, the shared limit key, the suffix, and the generated final account ID.

Services should not store raw IP addresses or raw connection strings in identity records.

Credential values, claim tokens, and one-time codes should continue to be stored as hashes.

Why I think this belongs in auth.md

auth.md already standardizes the anonymous-start and claim flow. Once anonymous-start grants real trial value, services need a common way to meter that value.

This proposal does not require auth.md to prescribe one infrastructure model, one IP model, one provider, or one account ID format. It only gives services a shared vocabulary for origin-aware limits in the anonymous registration path.

Open questions

1. Are channel, source, and user the right names for the optional anonymous request fields?
2. Should the service-derived connection concept be named in the spec even though it is not part of the request body?
3. Should auth.md recommend fallback values such as unknown, unknown, and anonymous for anonymous-start registrations?
4. Should the spec explicitly recommend separating the shared limit key from the final account/workspace ID?
5. Should the spec include guidance that active-unclaimed caps exclude claimed and expired accounts?

We implemented this model in our own SaaS platform work and would be happy to adapt the terminology or shape if there is a better fit for auth.md.

[sergeliatko]

original doc from repo:

authmd-agent-origin-registration.md

[m0tzy]

Hi Serge! How do you propose validating that the fields in the anonymous profile are trustworthy? They don't seem to have a ton of value since they can be easily spoofed.

[sergeliatko]

@m0tzy

Hi Madison,

Short answer: I don't validate channel, source and user, and as a platform I shouldn't. I treat them as untrusted by design. They're self-declared origin hints: optional, possibly empty, useful for honest users and for my own stats, never the basis for a trust decision.

That's fine, because the protection here isn't trust, it's economics. My goal is to let anyone try the product with no human present, get real value, and hopefully bring a buyer. So I have to assume every free account is farmed and make sure a farmed one is worthless. Three levers do that, and none of them depends on the fields being honest.

A hard global cap per installation. I decide the most unclaimed accounts that may exist at once regardless of source, say 100, and that ceiling bounds my total exposure no matter how the inputs are forged. I keep per-axis velocity limits on top, but the global cap is the backstop that trusts nothing.

A short life. Unclaimed trials can expire in as little as a couple of hours, so a farmed account is gone before it is worth reselling.

A small entitlement. Anonymous gets a handful of operations and roughly 20% of what a verifiable user/agent gets. There just isn't enough value in one account to make farming pay.

The one signal the caps do rely on is the connection, and that isn't an input the agent controls: by the time the cap code runs in the platform kernel, the request has passed the edge and the router, and the connection comes from the headers my infrastructure sets, not from the body.

So the fields earn their place by helping honest users stay honest, not by being trustworthy, and the abuse story holds even if all three are spoofed.

What I'd pin in the spec is exactly that: name channel/source/user as untrusted origin hints, and make clear the service's defense is its own economics and caps, not the contents of those fields.

[sergeliatko]

On their usefullness: a special deal for a channel or specific source baked on their end and trackable on my end...

If someone gets a hold of the exact combination and signs up, why not? If I see too many "spoofed" accounts came from "appWhatEver" because their bots decided to farm, I can add a dynamic rule to shut that down, with no human action on my behalf.

I see them more like "honeypot" fields that can be hijacked by honest users or agents to bring me stats for analytics and smart caps rules. Better than having no optional fields and pushing the auth.md standard adopters to invent their own wheels with headers or field zoo just to setup affiliate deal, or keep stats running.

[anxovatomica]

If anyone still needs this, I recently made Free Invoice Generator: https://anxovatomica.github.io/invoice-generator/

Create professional invoices in seconds — no signup, no watermarks, instant PDF download.

Free, open-source, instant. No accounts or anything. Feel free to use it!

[m0tzy]

My hunch is that these don't belong in the protocol spec / reference implementation. You can add them to your implementation, but they're not globally applicable fields.

Where do you expect the agent to retrieve these values from? Will they be encoded in your AUTH.md file?

I understand that you want to treat them as honeypot fields, but that's a nuance that's difficult to explain to people who are just skimming field names.

[sergeliatko]

@m0tzy

Hi Madison, all fair, and I think the gap is smaller than it looks. Let me lay it out more clearly.

The business need

The protocol exists to make a business run, and this is a concrete business need. Once anonymous-start grants real trial value, the issuer has to meter it, and a single IP cap doesn't express what a business actually wants to do.

There's a control gap underneath it. The rate limits and caps that exist today are the provider's, tuned to protect the provider's API. As the business I have no lever there, and those limits don't carry my business meaning: which sources to favor, which to throttle, where to spend trial value. Without a shared origin axis I build that lever myself, off to the side, and so does everyone else.

Why the fields help even when they're spoofed

Two examples from my own use.

I bake a known channel/source into a partner's client and recognize that combination on my end to apply a special deal. If someone copies the combination and signs up, fine: it was never a security boundary, just a marketing lever I can still cap.

And if I see a flood of accounts claiming source "appWhatever" because someone's bots are farming, I can drop a dynamic rule that throttles that source automatically, with no human in the loop.

Both work whether the field is honest or spoofed. Honest values give me analytics and smart caps. Consistently spoofed values give me a pattern I can auto-block. Randomly spoofed values just fall back to the connection and global caps. Never trusted, useful in every case.

Optional, not required

I'm not asking for a required field. I'm asking for an optional one the spec defines, the same way HTTP defines User-Agent without requiring it. Optional and specified are not opposites, and User-Agent is the right parallel anyway: optional, never trusted, spoofable, and useful all at once.

Where the values come from

From the caller's own context at integration time. AUTH.md declares that the fields exist and are welcomed; it doesn't hold the values. And connection is never caller-supplied at all, the service derives it.

Why a standard matters more for scripts than for agents

This is the part that isn't really about agents.

An agent can read AUTH.md, meet an optional field it has never seen, reason about what it wants, and fill it. A plain script or API client can't. It won't infer the purpose of an unfamiliar optional field.

So if every installation names these differently, every integrator writes per-installation logic, or bolts an LLM onto a script, just to populate them. Standard names are what make these fields fillable by callers that have no intelligence behind them. Without that, the optional fields are effectively agent-only, and the apps and API calls that also use anonymous-start get nothing from them.

Why it belongs in the spec

The "hard to explain" concern is the argument for specifying, not against it. Explaining what's needed to make a thing work smoothly and safely is what a spec is for, and this is the best place to put it.

The real risk of leaving it out isn't just fragmentation. It's that people copy a working implementation without understanding it and trust these fields, which is the one mistake that opens a hole. A spec that names them, states plainly they must never be trusted, and explains why, prevents that.

The community will also converge on something here regardless, because business applications force it. The only question is whether that happens once, at the root, with a clear security explanation, or as a dozen private interpretations that each adopter reverse-engineers and that each get the trust boundary wrong in their own way.

What I'm asking for

Name it at the root as recommended guidance, not a protocol requirement, and keep the depth in a linked note. Concretely:

• Define the optional fields and their purpose, and make explicit that they are optional, not required, and not part of the protocol itself.
• State clearly what they are, that they must never be trusted, and why.
• Link to a standalone best-practice article that carries the full reasoning: where the fields are useful, the use cases, how a service builds throttle and cap limits from them, and the service-derived connection field, including how it should be derived and what it is for. That depth belongs in its own document where there's room to do it well, and I'm happy to draft it.

Not required, and not part of the protocol. Just named at the root and pointed at a proper explanation, so the next implementer gets it right instead of opening a hole.

[sergeliatko]

@m0tzy

Where do you expect the agent to retrieve these values from? Will they be encoded in your AUTH.md file?

Yes

[m0tzy]

I don't think I follow, how does the agent know what to provide for these values on the registration request?

Where the values come from
From the caller's own context at integration time. AUTH.md declares that the fields exist and are welcomed; it doesn't hold the values. And connection is never caller-supplied at all, the service derives it.

[sergeliatko]

The file auth.md explains the fields schema agent reads it and sends data:

curl.exe -X POST "http://www.techspokes.com/agent/auth" -H "Content-Type: application/json" -d '{"type":"anonymous","action":"register","channel":"agent","source":"codex","user":"serge"}'

The payload you see was just built by agent with almost no explanation at all (schema may be wrong as I typed it in ) which proves the honest agent will try to fill what it can...

And whatever they fill there is already enough to serve it's purpose.

Btw the agent knew the fields were optional in the payload.

Also note how the lack of recommendation and good rationale/explanation about what those fields are in the spec, made my codex leak my username? That's why a recommendation on the specs with a good explanation of " do and don't " is almost a must to avoid issues on both sides.