Handling Unknown Users (Reject vs Create)
Deciding what happens when an agent presents a valid token not in your database — reject with ACCOUNT_REQUIRED or enable explicit signup.
Every integration meets the same moment: a genuine token, verified signature and all, for an email that is not in your users table. There are exactly two answers, and this page is how to pick yours honestly.
The two answers
| Reject | Create | |
|---|---|---|
| Function | verifyAgentAccount everywhere | verifyAgentAccount everywhere, createAgentAccount in one signup handler |
| Unknown identity gets | 403 ACCOUNT_REQUIRED → human connects their account, agent retries | 403 ACCOUNT_REQUIRED → agent calls your signup endpoint itself, then retries |
| Human step | Yes — connecting is a human act | No — the agent does both steps |
| Account appears | Only by a human connecting | By the agent, at the signup endpoint, and nowhere else |
Reject, if any of these is true
- Your service serves only existing customers, a closed beta, or anything where an unknown person must not get in.
- You cannot staff the abuse surface below — see it plainly before you opt out of it.
- You have a connect flow already (OAuth to your own product, an invite link, a human signup page). The
403row points at it.
Rejecting is the default. You do not configure it; you get it by never importing the creating function.
Create, if all of these are true
- A stranger with an account is a customer, not an incident — the way a human filling in your registration form is.
- You can staff the abuse surface: spam, scraping, terms-of-service bypass, and support load you cannot attribute to anyone. Creation does not add a new kind of attacker — any AgentOnboard user could already present a genuine identity to you — but it turns reads into writes at scale, and that is a bigger surface to hold.
- You publish the signup endpoint in
auth.mdand keep it published. An unmentioned capability is one the agent will not use.
Creation is stranger self-registration, by design
Say it plainly before you ship it: anyone with a valid AgentOnboard token can call your signup endpoint and get an account, the same way anyone can fill in a human registration form. If that sentence alarms you, reject. The explicit signup step makes creation intentional; it does not make it permissioned.
What both answers share
- Revoking an API key does not delete anything. It stops future minting. An account created at your service stays created, and nothing in our system can remove it.
- The created account is a normal account. No global restriction flag exists. If agent-created accounts should be limited — no invites, no API keys, a trial tier — that is a column on your table, enforced in your layer.
- You can switch later, in either direction. Rejecting today and creating tomorrow is one new handler plus one new
auth.mdrow. Creating today and rejecting tomorrow is deleting the handler and pointing the row at your connect flow. Neither direction migrates data, because neither direction changes the shape of an account.
The question to ask in the room
Not "is signup safe" — nothing here is permissioned, so that is the wrong test. Ask: "if a thousand strangers got accounts tonight with no human clicking anything, would that be a launch or an incident?" Launch means create. Incident means reject. Everything else on this page is commentary about that answer.