feat: add business unit CRUD, team assignment, and governance endpoints to OpenAPI spec

[impoiler]

Summary

Introduces Business Units as a new Enterprise governance entity — an organizational grouping that sits above teams (one business unit to many teams) and supports its own budget and rate limit governance. Also expands model config limits with multi-budget support, scoping (global/virtual_key/user), and calendar-aligned resets, and adds a SessionCookieAuth security scheme for dashboard session endpoints.

Changes

• Added a full CRUD API for business units under /api/governance/business-units, including list (paginated, searchable), create, get, update, and delete operations.
• Added team assignment endpoints (POST /api/governance/business-units/{id}/teams and DELETE /api/governance/business-units/{id}/teams/{teamId}) to associate and unassociate teams from a business unit. A team can only belong to one business unit at a time (409 on conflict).
• Added governance sub-resource endpoints (POST/PUT/DELETE /api/governance/business-units/{id}/governance) to configure, update, and remove budget and rate limit governance on a business unit.
• Replaced the single budget field on ModelConfig, CreateModelConfigRequest, UpdateModelConfigRequest, and provider governance schemas with a budgets array supporting multiple budget lines per model limit, each with a unique reset_duration. The legacy budget field is retained for backward compatibility.
• Added scope (global, virtual_key, user) and scope_id fields to model config schemas to allow per-virtual-key and per-user model limits.
• Added calendar_aligned flag to model config and provider governance schemas to enable budget resets at clean calendar boundaries.
• Renamed count to total_count in ListModelConfigsResponse to better reflect its role in pagination.
• Updated listModelConfigs to be paginated with limit, offset, search, scope, provider, and from_memory query parameters.
• Removed ManagementBearerAuth requirement from the session login, session info, and OAuth callback endpoints (they are now unauthenticated or use other mechanisms).
• Added SessionCookieAuth as an accepted security scheme on session logout and WebSocket ticket endpoints, alongside ManagementBearerAuth.
• Updated the /api/keys/virtual endpoint to accept VirtualKeyAuth, BearerAuth, and ApiKeyAuth instead of ManagementBearerAuth.
• Added the SessionCookieAuth security scheme definition (HTTPOnly token cookie set by the login endpoint).
• Added new OpenAPI source files: docs/openapi/paths/management/businessunits.yaml and corresponding schemas in docs/openapi/schemas/management/governance.yaml.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

go test ./...

• Create a business unit via POST /api/governance/business-units and verify it is returned by GET /api/governance/business-units.
• Assign a team to the business unit and confirm a 409 is returned when attempting to assign the same team to a different business unit.
• Configure governance on the business unit via POST /api/governance/business-units/{id}/governance and verify budget/rate limit are reflected in GET /api/governance/business-units/{id}.
• Delete the business unit and confirm assigned teams are unassigned atomically.
• Create a model config with multiple budgets entries and verify the legacy budget field still returns the first entry.
• Verify that session login and OAuth callback endpoints no longer require a management bearer token.
• Verify that session logout accepts both ManagementBearerAuth and the token session cookie.

Breaking changes

• Yes
• No

count in ListModelConfigsResponse has been renamed to total_count. Clients reading this field will need to update accordingly. The legacy budget field on model config and provider governance responses is deprecated in favour of budgets but remains present for backward compatibility.

Related issues

Security considerations

The session login and OAuth callback endpoints have had ManagementBearerAuth removed, making them publicly accessible as intended for unauthenticated flows. The new SessionCookieAuth scheme uses an HTTPOnly cookie, limiting XSS exposure for dashboard session authentication.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

Summary by CodeRabbit

• New Features

  • Business Units management (CRUD), team assignment/removal, and governance (budget/rate-limit) endpoints.
  • Business Unit governance supports create/update/delete of budget and rate-limit associations.

• Documentation

  • API docs updated for new endpoints, paginated responses, and request/response shapes.
  • Expanded scope options for model-configs listing to include "user" (Enterprise-only).

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

📝 Walkthrough

Walkthrough

Adds OpenAPI management paths and schemas for Business Units (CRUD, team assignment, governance configuration) and expands the model-configs GET scope enum to include user (Enterprise-only).

Changes

Business Units and Model Configs Governance API

Layer / File(s)	Summary
Business Unit schemas docs/openapi/schemas/management/governance.yaml	Adds BusinessUnit, list/detail responses, CreateBusinessUnitRequest, mutation responses, team-assignment/listing schemas, and governance mutation schemas (CreateBusinessUnitGovernanceRequest, UpdateBusinessUnitGovernanceRequest, BusinessUnitGovernanceResponse).
Top-level OpenAPI paths wiring docs/openapi/openapi.yaml, docs/openapi/openapi.json	Inserts /api/governance/business-units* top-level path entries and updates generated JSON to include the new Business Units section.
Business Unit collection & item endpoints docs/openapi/paths/management/businessunits.yaml, docs/openapi/openapi.json	Defines listBusinessUnits (GET) and createBusinessUnit (POST) plus per-id getBusinessUnit/updateBusinessUnit/deleteBusinessUnit operations with ManagementBearerAuth and explicit response mappings.
Team association endpoints docs/openapi/paths/management/businessunits.yaml, docs/openapi/openapi.json	Adds listBusinessUnitTeams (GET), assignTeamToBusinessUnit (POST with 409 on conflict), and removeTeamFromBusinessUnit (DELETE) with pagination/search and error responses.
Business Unit governance operations docs/openapi/paths/management/businessunits.yaml, docs/openapi/openapi.json	Adds createBusinessUnitGovernance (POST), updateBusinessUnitGovernance (PUT) — documenting that empty budget/rate_limit objects remove components — and deleteBusinessUnitGovernance (DELETE), with conflict and error mappings.
Model-configs scope enum update docs/openapi/openapi.json, docs/openapi/paths/management/governance.yaml	Expands scope query parameter enum for model-configs GET from ["global","virtual_key"] to ["global","virtual_key","user"] (noted Enterprise-only) and updates descriptions accordingly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• maximhq/bifrost#3982: Overlapping model-configs contract and schema changes (budgets array, total_count, and related model-limits documentation).
• maximhq/bifrost#3813: Related governance/schema tightening around budgets→budgets and scope semantics.

Suggested reviewers

• danpiths
• akshaydeo
• roroghost17

Poem

🐰 I nibble specs beneath the moonlight bright,
New units sprout and teams find homes tonight,
Budgets arrayed and scopes grow by one,
Docs hum softly — governance work is done! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding business unit CRUD, team assignment, and governance endpoints to the OpenAPI spec.
Description check	✅ Passed	The description comprehensively covers all required sections with detailed explanations of changes, type of change, affected areas, testing steps, breaking changes, and security considerations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 06-05-docs_governance_business-units_apis

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[impoiler]

• fix: broaden Mantle model matching to all gpt variants #4091
• test: remove TestCollectApplicableGovernanceIDs_UserScopedModelConfigs #4090
• feat: add business unit CRUD, team assignment, and governance endpoints to OpenAPI spec #4082 👈 (View in Graphite)
• feat: add inline loading shell to #root before React mounts #4063
• fix: reduce FTS index left() cap from 800k to 250k chars to stay within tsvector limit #4057
• feat: add alias column to materialized view and filter support #4078
• feat: add "View logs" menu item to customer, team, and virtual key tables #4073
• feat: extract BudgetDisplay component with progress bar and tooltip #4055
• feat: add clickable links for routing rule, selected key, virtual key, and prompt in log detail views #4054
• fix: standardize page container layout with no-padding-parent and 100dvh sizing #4046
• fix: add colored tooltip values and subtle cursor highlight to dashboard charts #4044
• feat: add customer detail sheet and remove inline usage section from customer sheet #4026
• fix: replicates vk hierarchy flow for ghost nodes reconcilation #4088
• feat: supports multiple customers logs and usage tracking #4066
• fix: fixes virtual key model configs UI #4052
• fix: fixes cascade deletes for model configs #4051
• feat: adds support for multiple team and bu units in logstore #4041
• feat: adds team budget and rl collection exporters #4040
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Confidence Score: 5/5

Additive OpenAPI spec changes only — no Go implementation, no runtime paths, no migrations in this diff. Safe to merge.

All changes are documentation additions to the OpenAPI spec. The three findings are schema-completeness gaps that do not affect the server runtime behavior and can be iterated on independently.

docs/openapi/schemas/management/governance.yaml — BusinessUnitDetailResponse and BusinessUnitGovernanceResponse schema shapes.

Important Files Changed

Filename	Overview
docs/openapi/paths/management/businessunits.yaml	New file defining CRUD + team assignment + governance endpoints for Enterprise business units. Path parameters, security, and paginated list patterns are consistent with the existing governance API, with minor concerns around the missing update endpoint and the response shape for governance operations.
docs/openapi/schemas/management/governance.yaml	Adds 188 lines of business unit schemas. The CreateBusinessUnitGovernanceRequest correctly uses anyOf to enforce at least one of budget/rate_limit. BusinessUnitDetailResponse lacks required constraints and non-nullable refs, and BusinessUnitGovernanceResponse embeds the full internal BusinessUnit schema inconsistently with the slimmer CRUD GET response.
docs/openapi/paths/management/governance.yaml	Minor: adds user (Enterprise-only) to the scope filter enum for listModelConfigs. Clean change.
docs/openapi/openapi.yaml	Registers the five new business unit path groups; path parameters use consistent snake_case. No issues.
docs/openapi/openapi.json	Compiled JSON representation of the YAML changes. Derived artifact; issues are in the YAML sources.

_{Reviews (7): Last reviewed commit: "docs: governance/business-units apis" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/openapi/openapi.json`:
- Around line 39491-39529: The paginated "Paginated list of business units"
response object is missing a required array; update the schema for the object
(the one with description "Paginated list of business units") to include a
"required": ["business_units","total","page","limit"] entry so clients can rely
on those fields, and apply the same change to other paginated responses (e.g.,
the "teams list" paginated schema) to mark their top-level pagination fields
required; optionally also add required arrays inside the business unit item
object for essential fields like "id" and "name" if those must always be
present.
- Around line 40069-40095: The path parameter name uses camelCase `{teamId}` but
must be snake_case to match the API spec and the request body; update the
OpenAPI path and parameter for the removeTeamFromBusinessUnit operation so the
path key becomes "/api/governance/business-units/{id}/teams/{team_id}" and the
corresponding parameter object (name and any references) uses "team_id" (type
string, in: path, required: true); also search within the
removeTeamFromBusinessUnit operation for any examples, $ref or schema entries
referencing "teamId" and change them to "team_id" to keep the operation
consistent.
- Around line 40952-40961: The OpenAPI spec for GET
/api/governance/model-configs currently restricts the query parameter named
"scope" to enum ["global","virtual_key"], but ModelConfig.scope
(components/schemas/ModelConfig.scope) and the handler/configstore accept "user"
as a valid value; update the "scope" query parameter definition in openapi.json
for the GET /api/governance/model-configs endpoint to include "user" in its enum
and add a description annotation indicating that "user" is Enterprise-only (or
alternatively document why it is intentionally excluded) so OpenAPI tooling
reflects actual behavior.

In `@docs/openapi/schemas/management/governance.yaml`:
- Around line 839-849: The schema for CreateBusinessUnitGovernanceRequest
currently allows an empty object even though the description requires at least
one of budget or rate_limit; update the CreateBusinessUnitGovernanceRequest
schema to enforce this by adding an anyOf (or oneOf) clause that requires either
the property "budget" or the property "rate_limit" (referencing the existing
budget and rate_limit properties), so the schema validation matches the prose.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 023206fd-22c7-450a-a964-eb3661062fa1

📥 Commits

Reviewing files that changed from the base of the PR and between 8c43dd1 and b4fe5d7.

📒 Files selected for processing (4)

• docs/openapi/openapi.json
• docs/openapi/openapi.yaml
• docs/openapi/paths/management/businessunits.yaml
• docs/openapi/schemas/management/governance.yaml

[akshaydeo]

Merge activity

• Jun 5, 2:00 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 5, 2:22 PM UTC: Graphite couldn't merge this PR because it had merge conflicts.
• Jun 5, 2:35 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 5, 2:36 PM UTC: @akshaydeo merged this pull request with Graphite.