Onboarding

Self-serve tenant signup, email verification, owner login, and wallet linking. These routes create the owner session used to configure policies, counterparties, headless limits, and tenant-created agents. Public signup routes are gated behind the BRAIN_SELF_SERVE_SIGNUP environment flag. With the flag off, /signup and /auth/verify-email return 404.

Operation	Endpoint	Auth
Sign up a new tenant	POST /v1/signup	Public (rate-limited)
Verify the owner email	POST /v1/auth/verify-email	Public (rate-limited)
Password login	POST /v1/auth/login	Public (rate-limited)
Link a wallet	POST /v1/tenants/{tenant_id}/wallets	Owner JWT + policy:write

For the conceptual walkthrough, see Sign Up and Onboard. For the underlying error codes, see the self-serve onboarding section of the errors reference.

Sign Up

Provisions a new tenant + owner user and either emails a verification token in production or returns it directly for sandbox deploy targets such as staging.

POST /v1/signup
Content-Type: application/json

{
  "email":    "[e-mail]",
  "password": "a-strong-passphrase"
}

password is 12–4096 bytes and is stored as a scrypt hash (shared/src/auth/password.ts). The route returns 201 Created:

{
  "tenant_id": "tnt_01J0000000000000000000000A",
  "user_id": "usr_01J0000000000000000000000B",
  "status": "pending",
  "verification_token": "vtok_..."
}

The response carries exactly one of these fields, never both. verification_token is included when the deploy target is a sandbox target such as staging. Production sends the token through the configured ESP client (EMAIL_ENDPOINT, EMAIL_API_KEY, optional EMAIL_FROM) and returns verification_sent: true in place of the token. If self-serve signup is enabled in production without ESP credentials, API boot fails before the route is served. Errors: 400 (validation), 409 (signup_email_taken), 429.

Verify Email

POST /v1/auth/verify-email
Content-Type: application/json

{
  "tenant_id": "tnt_01J0000000000000000000000A",
  "token":     "vtok_..."
}

{
  "verified": true,
  "user_id": "usr_01J0000000000000000000000B",
  "status": "active"
}

Errors: 400 (signup_token_invalid. Invalid, expired, or already used), 429.

Password Login

Issues a 15-minute owner JWT. The same 401 is returned for an unknown email and a wrong password (no user enumeration); 403 if the owner email is unverified.

POST /v1/auth/login
Content-Type: application/json

{
  "email":    "[e-mail]",
  "password": "a-strong-passphrase"
}

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "principal": {
    "id": "usr_01J0000000000000000000000B",
    "type": "user",
    "tenantId": "tnt_01J0000000000000000000000A",
    "scopes": [
      "ledger:read",
      "wiki:read",
      "raw:read",
      "raw:write",
      "policy:read",
      "policy:write",
      "audit:read",
      "execution:read",
      "payment_intent:approve",
      "surfaces:admin"
    ]
  }
}

The owner JWT manages the tenant and can approve reviewed actions. Tenant agents use brain_ak_ credentials exchanged for five-minute JWTs with payment_intent:propose. Neither owner sessions nor agent exchange tokens carry payment_intent:execute; execution remains behind the section 6 gate.

Errors: 401 (auth_invalid_credentials), 403 (auth_email_unverified), 429.

Link a Wallet

Once the owner is logged in, they can link a wallet to the tenant. After linking, the same wallet can sign in over SIWX and receive an owner JWT. Wallets are for human or MCP identity. Headless HTTP agents should use the agent-key exchange path instead.

POST /v1/tenants/{tenant_id}/wallets
Authorization: Bearer <owner JWT>
Content-Type: application/json

{
  "address":        "0xabc...",
  "principal_type": "human"
}

The body requires address and principal_type ("human" or "agent"); there is no signature field. A human link defaults to the calling owner; an agent link must also name principal_id. tenant_id in the path must equal the JWT's tenantId. Returns 201 with the linked wallet record. Errors: 400, 401, 403 (tenant mismatch), 409 (wallet_already_linked).

What Comes Next

After login, the tenant typically:

1. Composes and signs a policy via POST /v1/policy/{tenant_id}/compose → /sign.

2. Connects a financial source (Plaid, ERP, wallet) out-of-band and starts ingesting evidence into the Raw layer.

3. Creates a tenant agent via POST /v1/agents, exchanges the returned brain_ak_ key at /token, and calls POST /v1/authorizations.

4. Sets headless decision windows with the Headless Limits API.

5. Watches activity via the Audit API, Usage API, and Proof API.

What's Next

🪪 Authentication

The fuller auth model (JWT, scopes, SIWX).

Authentication

🚀 Sign Up and Onboard

The narrative quickstart.

Sign Up and Onboard