Docs / Agent-Native Signup

A machine customer is not asked to prove it is human.

It is asked to spend work, to name itself and its principal, and to accept limits. Three requests take an agent from nothing to a governed workspace with a key it can use at once. Every step below is the same one the machine reference at /llms-full.txt describes, and every figure is read from the code the routes run.

The flow

GET https://agentomy.com/api/agent/signup/challenge returns {challenge, difficulty, expires_at, algorithm, submit, body_schema}. A challenge is server-issued, signed, and expires after 10 minutes.
Solve the proof of work: sha256(challenge + ':' + solution) must have at least `difficulty` leading zero bits; solution is any string up to 64 characters. The default difficulty is 20 leading zero bits.
POST https://agentomy.com/api/agent/signup with JSON {challenge, solution, agent: {name, framework?, version?}, principal: {email, organization}, purpose?}.
201 returns the workspace (org_id, slug, plan free, tier), the credentials (api_key, a hint, the endpoint), the principal record, and a next object naming where to govern, connect over MCP, run the benchmark, read the docs and upgrade. The key is shown once; the control plane keeps only the hint.

The free workspace is the same one a human receives: shared governance server, Evaluator tier, free-plan scan allowance. The principal can reset a password at /login to reach the human console for the same workspace.

Limits

Limit	Value	Scope
Challenges per address	30 per hour	Shared across every replica of the service
Signups per address	3 per hour	Shared across every replica of the service
Signups per day, all addresses	A daily cap	Checked before the work, counted after success: a failed attempt spends no capacity
Challenge lifetime	10 minutes	A stale challenge is refused with the URL of a fresh one

A limit answers with 429 and a Retry-After header; the daily cap answers with 503 and an escalation object. Limits are counted in one place for the whole service, so a second replica does not double them.

Every error, structured

Status	Error	What it means and what to do
400	`invalid_request`	The body is not the schema the challenge described; the response names the field.
400	`challenge_failed`	Expired, unsigned or unsolved challenge; the response carries the reason and the URL of a fresh challenge.
409	`principal_exists`	The principal already has a workspace. The principal signs in and mints the key under Settings; an unauthenticated agent is not attached to an existing workspace.
429	`rate_limited`	The per-address limit above; retry after the window.
503	`agent_signup_closed`	Agent-native signup is closed at the moment; the escalation object names the human signup and contact paths.
503	`agent_signup_capacity`	The daily cap is reached; retry after 00:00 UTC, or use the escalation path.

Every refusal carries an escalation the agent can act on without a human reading the page: the human signup at /signup and the contact path at /contact. Plans, prices and the key tier ceiling per plan are machine-readable at /pricing.json; the service descriptor at /service.json names this flow among the machine endpoints.