Identity Bridge: Machine-to-Dashboard Account Linking

2026-03-14

identityauthprovisioningdashboard

What We Built

Identity Bridge closes the gap between BrainstormRouter's two registration paths: machine registration (POST /v1/register) and OAuth provisioning (POST /auth/provision). Previously, a machine-registered tenant had no way to manage its resources from the dashboard — the two identity systems were completely isolated.

Now, machine registration returns a claim token alongside the API key. Opening the claim URL in a browser links the user's OAuth identity to the machine-registered tenant, creating a per-tenant actor row and a tenant_memberships record. A single OAuth identity can now manage multiple tenants through the dashboard via the X-BR-Tenant-Id header.

Why It Matters

Headless-first platforms need browser access eventually. Every AI agent that registers via API will eventually need a human to view analytics, manage keys, or configure guardrails. Identity Bridge makes this seamless: the claim token is proof-of-possession, the linking is atomic, and multi-tenant support means one person can manage their entire fleet from a single dashboard login.

How It Works

Registration with claim token:

curl -X POST https://api.brainstormrouter.com/v1/register \
  -d '{"invite_code":"...", "tenant_name":"My Lab", "admin_email":"me@lab.ai", "accept_tos":true}'

# Response includes:
# "claim": { "token": "brct_...", "url": "https://brainstormrouter.com/dashboard/?claim=brct_..." }

Claiming via SDK:

const link = await client.identityBridge.generateClaimLink({ role: "admin" });
console.log(link.url); // Share with teammate

Device flow (for terminal-to-browser linking):

const { user_code } = await client.identityBridge.authorizeDevice();
console.log(`Enter code ${user_code} at ${verification_uri}`);
// Poll: await client.identityBridge.pollDeviceToken(device_code);

Auth resolution: lookupTenantCtx() now uses resolve_tenant_memberships() → membership list → pick by X-BR-Tenant-Id header. Falls back to lookup_user_by_external_id() for backward compatibility.

The Numbers

2 new tables: tenant_memberships, claim_tokens
2 new SECURITY DEFINER functions: resolve_tenant_memberships, lookup_claimable_by_email
4 call sites updated to membership-aware resolution (auth middleware, provision, PKCE, workspace)
7 new API endpoints across 3 phases (claim, device, link)
0 test regressions (29 pre-existing failures unchanged)

Competitive Edge

No other AI gateway offers seamless machine-to-human identity linking. Portkey and OpenRouter require manual dashboard setup before API access. BrainstormRouter lets agents self-register and hand off management to humans when ready — true headless-first architecture with human-in-the-loop when needed.

Lockstep Checklist

[x] API Routes: src/api/routes/identity-bridge.ts (new), src/api/routes/auth.ts (modified)
[x] TS SDK: packages/sdk-ts/src/resources/identity-bridge.ts (new), exported from index
[x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/identity_bridge.py (new), exported from __init__
[x] MCP Schemas: N/A (not agent-facing tools)
[ ] Master Record: Update pending