> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/platform/sign-up-and-onboard.md).

# Sign Up and Onboard

Go from zero to an authenticated sandbox tenant and tenant agent.

This page is optional for headless integrations.

Self-serve onboarding provisions a **sandbox tenant** you can read and *propose* against immediately. Real money stays behind the promotion + external-audit gates, so onboarding is safe to explore end-to-end.

{% hint style="info" %}
Self-serve signup is gated by the `BRAIN_SELF_SERVE_SIGNUP` flag. A new tenant starts in sandbox with a review-first policy and conservative headless limits. Two principal classes share one tenant: a human owner for setup, reads, approvals and agent issuance, and tenant agents that exchange a one-time `brain_ak_` credential for a five-minute propose-only JWT. No self-serve token carries execute scope.
{% endhint %}

### 1. Sign up

```bash
curl -sX POST "$BRAIN/v1/signup" -H 'content-type: application/json' \
  -d '{"email":"founder@example.com","password":"a-strong-passphrase-12+"}'
# → 201 { "tenant_id":"tnt_…", "user_id":"user_…", "status":"pending",
#         "verification_token":"…" }   # returned outside production; emailed in prod
```

Password is min 12 chars (stored as a scrypt hash). A duplicate email returns `409 signup_email_taken`. In production, the API sends the verification token through the configured ESP client and fails at boot if self-serve signup is enabled without ESP credentials.

### 2. Verify your email

```bash
curl -sX POST "$BRAIN/v1/auth/verify-email" -H 'content-type: application/json' \
  -d '{"tenant_id":"tnt_…","token":"<verification_token>"}'
# → 200 { "verified": true, "status": "active" }
```

Single-use, short-TTL token scoped to your tenant.

### 3. Log in for an owner token

```bash
curl -sX POST "$BRAIN/v1/auth/login" -H 'content-type: application/json' \
  -d '{"email":"founder@example.com","password":"a-strong-passphrase-12+"}'
# → 200 { "access_token":"eyJ…", "expires_in":900,
#         "principal": { "type":"user", "scopes":["ledger:read","wiki:read",
#           "raw:read","raw:write","policy:read","policy:write","audit:read","execution:read","payment_intent:approve"] } }
```

Use it as a bearer token. It's tenant-scoped (RLS) and 15-minute-lived; log in again to refresh.

```bash
curl -s "$BRAIN/v1/ledger/accounts" -H "authorization: Bearer $ACCESS_TOKEN"
```

### 4. Create a headless agent

Use the owner token to create a tenant agent. The response returns the agent and one plaintext agent key exactly once.

```bash
curl -sX POST "$BRAIN/v1/agents" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"kind":"tenant","name":"Invoice Agent","purpose":"Request authorization decisions.","autonomy_preset":"ask_always"}'
# → 201 { "agent":{ "id":"agent_..." },
#         "api_key_once":"brain_ak_...",
#         "exchange":{ "token_endpoint":".../token", "resource":"..." } }
```

Exchange that key at `/token` for a five-minute JWT with `payment_intent:propose`, then call `POST /v1/authorizations` with `execution: "external"`. The decision path records policy and audit evidence but creates no PaymentIntent and moves no money. MCP agents still use the registered-agent and SIWX path for the MCP tool surface.

### What's Next

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Let an External Agent In</strong></td><td>Authorize a headless or MCP agent to read and propose.</td><td><a href="/platform/let-an-external-agent-in.md">Let an External Agent In</a></td><td></td></tr><tr><td><strong>Pay an Invoice Safely</strong></td><td>Propose, approve, execute, receipt.</td><td><a href="/platform/pay-an-invoice-safely.md">Pay an Invoice Safely</a></td><td></td></tr><tr><td><strong>Authentication</strong></td><td>The full credential and token reference.</td><td><a href="/api-reference/authentication.md">Authentication</a></td><td></td></tr></tbody></table>