# API Registration

A single endpoint — `POST /v1/signup` — gives you access. Choose between an instant sandbox key for testing or a full account with its own tenant after admin approval.

> **TL;DR for agents:** POST /v1/signup with `{email}` → instant sandbox key. Add `full_account:true, password, firstName` → full-account flow (email-confirm → ToS → admin approval). Same key throughout — auto-promoted on approve. Poll `/v1/me`.

## Two flows

Both flows go through the same endpoint `POST /v1/signup`. They differ only by the request body.

- **Sandbox** (default): instant `ldm_pk_*` bearer with quota 500/month. Outgoing messages are held for moderation (status `queued_for_moderation`).
- **Full account** (`full_account: true`): creates a User + Tenant + dedicated database after admin approval. Requires email confirmation and ToS acceptance.

## Sandbox flow — minimal request

```bash
curl -X POST https://api.live-direct-marketing.online/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com"}'
```

See the full verified response in [Quickstart](/quickstart#1-get-a-sandbox-key).

## Full-account flow — state machine

```bash
POST /v1/signup { email, password, firstName, full_account: true }
   -> registration_status = awaiting_email_confirm

User clicks confirmation link in email
   -> registration_status = awaiting_agreement

User clicks "I accept Terms" link in email
   -> registration_status = awaiting_admin_approval     # visible in admin panel

Admin approves
   -> User + Tenant + dedicated DB created
   -> scope = approved, registration_status = approved
Admin rejects
   -> waitlist & key deleted (no orphan User/Tenant created beforehand)

TTL: inactive >24h or pending approval >7d -> auto-deleted
```

## Polling for status

The `api_key` returned at signup is the **same** token throughout. While pending it has no API privileges — use it only for `/v1/me`. After approval the same key is auto-promoted — no rotation needed.

```bash
curl -H "Authorization: Bearer $API_KEY" https://api.live-direct-marketing.online/v1/me
```

Real sandbox response (verified):

```json
{
  "flow": "sandbox",
  "email": "agent@example.com",
  "scope": "sandbox",
  "moderation_status": "pending",
  "quota": {
    "monthly": 500,
    "used": 0,
    "remaining": 500,
    "resets_at": "2026-06-01T00:00:00.000Z"
  }
}
```

## Limits and security

- Signup rate limit: **5 per IP / hour** + a global ceiling of **50 / hour**. Exceeding either returns `429`.
- Request body limit on `/v1/signup`: **64 KB** (returns `413`).
- Password: minimum **10 characters**. Common passwords (e.g. `password`, `qwerty123`) are rejected with `400`.
- Extra fields in the request body are rejected with `400` (whitelist enforced).
- Re-using an email that already has a registered account returns the **same `201`** as a fresh signup — the existing account is never revealed, and the real owner receives a notification email.
- Email-confirm and ToS-acceptance links expire in **24 hours**.
- Pending admin approval expires in **7 days**.

## Request body — accepted fields

```json
{
  "email":        "string (required, valid RFC 5322, max 254)",
  "org":          "string (optional, max 200)",
  "use_case":     "string (optional, max 500)",
  "channel":      "form | a2a | mcp (optional)",
  "full_account": "boolean (optional, default false)",
  "password":     "string (required when full_account=true, min 10, max 200)",
  "firstName":    "string (required when full_account=true, max 80)",
  "lastName":     "string (optional, max 80)"
}
```