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.

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.

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

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

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.

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.

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.