Home Dashboard GitHub

Enterprise Documentation Consolidation — 5 Reference Pages, OAuth SDK Parity

2026-03-10

admin-apiscimoauthkmstenant-settingssdk-tssdk-pymcp

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["none (test coverage only — no route logic changes)"] sdk_methods_updated: ["client.oauth.listApps()", "client.oauth.createApp()", "client.oauth.deleteApp()"] mcp_tools_updated: ["none (test verification only — 5 admin tools already registered)"] ---

What We Built

Consolidated BrainstormRouter's enterprise infrastructure into a coherent, discoverable documentation layer. Five enterprise reference pages now cover the Admin API, SCIM 2.0 provisioning, OAuth PKCE authorization, BYOK/KMS envelope encryption, and tenant settings — capabilities that were already shipped and functional but had zero external documentation.

Added OAuth app management SDK parity: both the TypeScript and Python SDKs now expose client.oauth.listApps(), client.oauth.createApp(), and client.oauth.deleteApp(), wrapping the existing /v1/oauth/apps endpoints. The admin API received its first route-level test coverage with 17 tests across platform auth, tenant lifecycle, invite codes, and digest endpoints.

Why It Matters

Enterprise buyers evaluate platforms by their documentation quality and governance story. BrainstormRouter had the infrastructure — SCIM 2.0 for IdP sync, OAuth PKCE for third-party authorization, BYOK/KMS for key custody, and a full admin API for tenant lifecycle — but none of it was documented in a way that a CTO evaluating the platform could discover. This phase closes that gap: every enterprise capability now has a reference page with endpoint tables, code examples, and integration guidance.

How It Works

The enterprise docs are organized under a new Enterprise navigation group in docs.json, accessible from the Documentation tab. Each page documents the real API surface with working curl examples against api.brainstormrouter.com.

SDK OAuth parity follows the existing resource pattern: OAuth extends Resource (TS) and Resource/AsyncResource (PY), with typed methods for the three /v1/oauth/apps CRUD operations. The admin route tests use Hono's app.request() testing pattern with mocked service functions, verifying auth gates, dry_run behavior, status filters, and error responses.

The Numbers

  • 5 enterprise reference pages (admin, SCIM, OAuth, KMS, tenant settings)
  • 6 new SDK methods across TS and PY (3 per SDK)
  • 17 admin route tests covering auth, tenant lifecycle, invite codes, and digest
  • 5 MCP admin tools verified registered and callable

Competitive Edge

No AI gateway competitor documents enterprise governance at this level. Portkey and OpenRouter offer routing but not SCIM provisioning, BYOK encryption, or OAuth PKCE for third-party integrations. BrainstormRouter's enterprise story — now fully documented — positions it as the only platform where a CISO can evaluate IdP integration, key custody, and authorization flows from reference documentation rather than sales calls.

Deferred Enterprise Gaps

The following enterprise capabilities are documented but do not yet have route-level test coverage or full product-surface integration. They are explicitly deferred, not implied:

  • SCIM route tests: SCIM 2.0 endpoints (/scim/v2/*) are shipped and documented but lack route-level tests. Mock complexity (IdP-facing filter/pagination behavior, bearer token auth) exceeds this phase's budget.
  • OAuth route tests: OAuth PKCE consent flow endpoints (/auth/oauth/*) are shipped and documented but lack route-level tests. Consent flow requires Supabase JWT mocking. SDK tests cover the app CRUD subset (/v1/oauth/apps).
  • KMS bridge tests: BYOK/KMS endpoints (/auth/tenant/kms/*) are shipped and documented but lack route-level tests. Bridge behavior is a thin proxy — covered by existing auth bridge patterns.
  • Tenant-settings bridge tests: Tenant settings endpoints (/auth/tenant-settings) are shipped and documented but lack route-level tests. Deep merge behavior is config-store-level, not route-level.
  • Dashboard enterprise pages: SCIM config, OAuth app management, KMS config, and tenant settings pages are not in the dashboard. Requires new JWT bridge endpoints in auth.ts and the repo has no dashboard test framework.
  • SCIM token management API: Design decision needed — admin-only vs self-service token provisioning.
  • SSO/OIDC config management API: Not yet designed.

Lockstep Checklist

  • [x] API Routes: No route logic changes — test coverage added for existing admin endpoints.
  • [x] TS SDK: packages/sdk-ts/src/resources/oauth.ts — OAuth resource with types and barrel exports.
  • [x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/oauth.py — OAuth + AsyncOAuth resources.
  • [x] MCP Schemas: No tool changes — verification tests confirm all 5 admin tools registered.
  • [x] Master Record: Enterprise capabilities documented in reference pages.