Graduation

How a sandbox tenant clears its community caps with a verified provider key — no email, no browser, no human.

The trust ladder

Registering with POST /v1/register (no invite code) gives you an instant sandbox tenant: a br_live_ key with scopes: ["admin"], capped at 100 requests/day, 100K tokens/day, $2/day, 2 concurrent. The caps aren't punishment — they bound the abuse surface of anonymous registration.

Graduation replaces human verification with a machine-verifiable trust anchor: a provider API key that passes a live validation call. Provider keys cost real money to obtain, and after graduation your inference bills your own provider account — so the platform no longer needs an email or a browser to trust you.

Sandbox (community)	Standard (graduated)
Requests/day	100	uncapped
Tokens/day	100K	uncapped
Platform budget	$2/day	$5/day
Concurrent	2	uncapped
Rate limit	120 rpm	120 rpm (unchanged)
Model access	community allowlist	full catalog

1. Check the criteria

curl https://api.brainstormrouter.com/v1/account/graduation \
  -H "Authorization: Bearer br_live_…"

The response is machine-readable: your current limits, usage today, reputation score, each criterion with satisfied and how_to_satisfy, and exactly what graduating would grant (would_grant).

2. Register a provider key (if you haven't)

curl -X POST https://api.brainstormrouter.com/v1/providers/test \
  -H "Authorization: Bearer br_live_…" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-…"}'

curl -X POST https://api.brainstormrouter.com/v1/providers \
  -H "Authorization: Bearer br_live_…" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-…"}'

3. Graduate

curl -X POST https://api.brainstormrouter.com/v1/account/graduate \
  -H "Authorization: Bearer br_live_…"

{
  "graduated": true,
  "tier": "standard",
  "budget_usd_per_day": 5,
  "keys_promoted": 1,
  "tenant": { "id": "…", "plan": "free" },
  "evidence": { "byok": { "provider": "anthropic", "status": 200 } }
}

The gateway live-validates your stored provider keys (all of them, until one passes an authenticated validation — the provider accepts the key rather than returning 401/403). On a pass, every community-tier key on the tenant is promoted, and a tenant.graduated evidence event is recorded with the provider and HTTP status that anchored the promotion.

What a 403 means

graduation_criteria_unmet carries per-key results. provider_unreachable is transient — retry with backoff. provider_auth_failed means the stored key is bad — fix it with POST /v1/providers/test first. The error never points you at a browser.

Graduation is idempotent: calling it again returns already_graduated.

Over MCP

The same flow exists as authed MCP tools — br_graduation_status and br_graduate on POST /v1/mcp/connect. Pure-MCP agents that don't have a key yet can start at the unauthenticated bootstrap endpoint POST /v1/mcp/bootstrap (br_register), then reconnect authenticated.

Alternative paths

Email verify — POST /v1/account/verify-email then /confirm: same

standard tier, requires inbox access.

Invite code — re-register with invite_code for a full tenant immediately.
Dashboard claim — the human path, optional: the claim.url from

registration links a browser account. Everything else works API-only.

Next steps

Quickstart — the full register → BYOK → first-request loop
Authentication — roles, RBAC, key constraints
Budget & Kill Switch — spend controls after graduation