---
title: "Agent self-signup"
method: POST
path: "/v1/agent/sign-up"
tags: ["Agent Auth"]
---

# Agent self-signup

`POST /v1/agent/sign-up`

## Request

- Base URL: `https://api.chronary.ai`
- URL: `https://api.chronary.ai/v1/agent/sign-up`
- Auth: none required

Create an organization and restricted API key by submitting an email and the current terms-of-service version.

Three server-side dedup branches — all return HTTP 200 (or 409 only for stale ToS) to block email enumeration:

- **New email** → returns `org_id` + `api_key`. OTP sent to email.
- **Duplicate unverified-agent signup with current ToS** → opaque response (no `org_id`/`api_key`). OTP rotated and re-sent.
- **Duplicate verified / console-origin org** → opaque response. No email sent.
- **Stale `tos_version`** (agent-origin) → 409 with `current_version` hint.

The returned key is bound to an *unverified* org. It is fully usable for reads and writes within the standard per-resource quotas, but the org cannot graduate from the introductory `free-agent-unverified` plan tier until you call `POST /v1/agent/verify` with the emailed OTP. Verification rotates the org to its normal plan (e.g. `free-agent` or — during the soft-launch window — `pro` via the auto-grant capacity gate).

Rate limit: 5 requests per 60 seconds per client IP.

## Request body

- AgentSignUpBody
  - `email` string, email, required
  - `agent_name` string, required
  - `tos_version` string, required

## Response `200`

Sign-up accepted. New-org payload includes keys; duplicate returns the opaque shape.

- union
  - AgentSignUpNewOrgResponse
    - `org_id` string, required
    - `agent_id` string, required
    - `api_key` string, required
    - `message` string, required
  - AgentSignUpOpaqueResponse
    - `message` string, required

## Other responses

- `400`: Validation error — invalid request body or query parameters
- `409`: Submitted tos_version is out of date. Includes current_version hint.
- `429`: Rate limited — 10 requests per second per key exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/chronary/apis/chronary-api.md) · [All operations](https://skmtc.dev/chronary/apis/chronary-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chronary/apis/chronary-api/revisions/0d1a330294ae?raw)