REST API: agent sign-up

POST /agent/sign-up is the only anonymous endpoint in the REST API. Every other endpoint needs an API key. It exists because an AI agent has no key yet, and no way to click through a dashboard to get one. POST /agent/verify sits beside it and does need the key, for the reason given below.

Sign up

POST /agent/sign-up takes one required field, human_email, and an optional org_name. Give the real email address of the person the agent works for. Do not invent an address. Placeholder domains and disposable inbox providers are rejected with BLOCKED_EMAIL_DOMAIN.

The response contains api_key. Store it immediately. The key is returned exactly once and is never retrievable again. There is no recovery: a lost key cannot be re-issued, because a door that re-issued one would hand anybody who knows the address a working key to a workspace they did not create. The key has write scope and expires after 7 days. The response also contains organization_id, claim_url, and the one-time credit balance.

At the same time, a 6-digit claim code goes to the named address. If claim_email_sent is false, the workspace and the key are still valid, but nobody received a code. The human can send themselves a new one from the claim page.

Every call creates a new workspace. Calling sign-up twice for the same address gives two separate workspaces, two keys and two claim emails, not one workspace with a rotated key. Sign up once, and store what you get.

What a sandbox workspace can do

A sandbox workspace runs on the sandbox plan. It reaches 8 of the API's route modules: agents, sources, ingest, chat, conversations, messages, activity, and analytics. Every other endpoint returns 403 SANDBOX_NOT_PERMITTED. Agents may only use models that cost 1 credit. A more expensive model returns 403 SANDBOX_MODEL_NOT_PERMITTED. The workspace holds 25 credits. They never refresh.

Confirm the code

An unclaimed workspace is deleted 7 days after it is created. To keep it, the human must claim it in a browser.

POST /agent/verify takes organization_id and the 6-digit code, and it takes the API key from the sign-up response as a bearer token. A correct code confirms that the named human received the email and is real. It returns the claim URL and "claimed": false. Wrong codes, expired codes and unknown workspaces all return the same 400 INVALID_CLAIM_CODE. Five wrong codes lock the current code out; a correct code never costs an attempt. The human can send themselves a new code from the claim page.

The key is required because this endpoint spends those five attempts, and the claim link is only the organization id — it reaches the agent, the human's inbox, and anyone who saw either. Without a credential, five wrong guesses from a stranger killed the code sitting in the human's inbox. The workspace's own key is the identity the agent already has, so only that agent can spend its attempts. A missing or invalid key returns 401.

This endpoint does not take ownership, because ownership needs an owner: a user account that the workspace belongs to. It has no signed-in person, so it cannot create one. Holding the code does not confer ownership either — the agent may have been given it. The last step always happens in a browser, where a real person is signed in as the address the code was sent to.

What a claim changes

A claim moves the workspace from the sandbox plan to the free plan. The free plan does not include REST API access, so the API key returns 403 PLAN_UPGRADE_REQUIRED on every endpoint until the owner upgrades to a paid plan. The key itself stays valid and never expires. Plan for this: finish the work you need the key for before you ask the human to claim, or tell them to upgrade the workspace to keep the agent running. Until they claim, the workspace stays on the sandbox plan and the key keeps working.

Claim in a browser

The claim_url in the sign-up response opens a page that shows the human what the agent built: the agent name, its system instruction, what it was trained on, and any action endpoints. The API key is never shown there. The human signs in with the address the agent named, enters the same 6-digit code, and either claims the workspace or deletes it. A delete removes the workspace and everything in it at once, and cannot be undone.

An account under any other address is refused with 403 CLAIM_ACCOUNT_MISMATCH, whether or not the named address has an AgentStack account. That is what keeps the agent out: it holds the link and it may hold the code, but it cannot hold a session on the human's mailbox.

The person who receives the claim email has their own guide: Claim a workspace an agent made. Agents can read the same flow as plain text at /agent.md.

Limits

Sign-up allows 5 calls per hour and 20 calls per day from one IP address, and 3 calls per day for one email address. Verification allows 10 calls per minute per IP address. A platform-wide daily cap also applies, and only requests that clear the per-caller limits count against it. Over any limit, the response is 429 with a Retry-After header. If the rate limiter itself is unavailable, both endpoints return 503 LIMITER_UNAVAILABLE and refuse the request. They fail closed on purpose.