docs(openapi): add missing management endpoints and split governance specs

[impoiler]

Summary

Briefly explain the purpose of this PR and the problem it solves.

Changes

• What was changed and why
• Any notable design decisions or trade-offs

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

Describe the steps to validate this change. Include commands and expected outcomes.

# Core/Transports
go version
go test ./...

# UI
cd ui
pnpm i || npm i
pnpm test || npm test
pnpm build || npm run build

If adding new configs or environment variables, document them here.

Screenshots/Recordings

If UI changes, add before/after screenshots or short clips.

Breaking changes

• Yes
• No

If yes, describe impact and migration instructions.

Related issues

Link related issues and discussions. Example: Closes #123

Security considerations

Note any security implications (auth, secrets, PII, sandboxing, etc.).

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

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Expanded API documentation with enterprise governance capabilities for users, teams, business units, RBAC, access profiles, virtual keys, customers, and related relationships.
  • Added webhook management, testing, secret rotation, delivery, and redelivery endpoints.
  • Added business-unit renaming, user-by-email lookup, and user governance operations.
• Documentation
  • Documented Enterprise availability across management features.
  • Updated pagination to use zero-based offsets and revised response fields.
  • Retained deprecated governance compatibility routes with successor references.
  • Clarified parameter names and expanded shared schemas and responses.

Walkthrough

The OpenAPI catalog adds enterprise governance, webhook, legacy compatibility, and management metadata. It updates pagination contracts, path parameter names, shared component registrations, governance schemas, and adds invariant validation.

Changes

Enterprise OpenAPI catalog

Layer / File(s)	Summary
Catalog and shared component registration docs/openapi/openapi.yaml	Registers governance and webhook paths, shared parameters, responses, and external schemas.
User and business-unit management contracts docs/openapi/paths/management/users.yaml, docs/openapi/paths/management/businessunits.yaml, docs/openapi/schemas/management/users.yaml, docs/openapi/schemas/management/governance.yaml	Adds governance operations, renames identifiers, changes pagination to offset, and updates response schemas.
Governance relationship operations docs/openapi/paths/management/governanceextensions.yaml	Documents virtual-key, user, team, customer, and business-unit relationships.
Access profiles and RBAC management docs/openapi/paths/management/accessprofiles.yaml, docs/openapi/paths/management/rbac.yaml	Adds Enterprise metadata and explicit profile_id, user_id, and role_id parameters.
Legacy governance compatibility routes docs/openapi/paths/management/governancelegacy.yaml	Adds legacy aliases with successor routes, operation identifiers, removal markers, and legacy pagination schemas.
Enterprise availability metadata docs/openapi/paths/management/auditlogs.yaml, docs/openapi/paths/management/circuitbreaker.yaml, docs/openapi/paths/management/mcptoolgroups.yaml, docs/openapi/paths/management/vault.yaml	Marks management operations as Enterprise-only and documents availability.
OpenAPI invariant validation docs/openapi/spec_invariants_test.py	Validates references, paths, fragments, operation IDs, legacy aliases, and successor routes.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• maximhq/bifrost#5650: Modifies the same governance, audit-log, and access-profile registrations.
• maximhq/bifrost#5831: Adds related management endpoint coverage, including webhooks.
• maximhq/bifrost#5841: Uses the governance routes, aliases, parameters, and pagination contracts documented here.

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR does not address issue #123 because it adds governance and management OpenAPI definitions but no Files API support such as POST /v1/files.	Add the required provider File API definitions and implementation, or remove issue #123 if it is not the intended objective.
Out of Scope Changes check	⚠️ Warning	The governance specifications, management endpoints, and invariant tests are unrelated to the linked Files API objective in issue #123.	Remove the unrelated governance changes or link the correct governance issues, and keep this PR focused on Files API support.
Description check	⚠️ Warning	The description reproduces the template without project-specific details, testing steps, selections, risks, or checklist completion.	Replace the template text with a completed summary, change list, affected areas, test steps, breaking-change status, security notes, related issues, and checklist.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the main changes: adding management endpoints and splitting governance specifications.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 08-04-docs_openapi_spec_sources

---

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

[impoiler]

• refactor: generate OpenAPI JSON and docs.json #5650 : 2 dependent PRs (#5652 , #6017 )
• docs: add governance API namespace migration guide #5841
• docs(openapi): add missing management endpoints and split governance specs #5840 👈 (View in Graphite)
• refactor(governance): allow editions to override governance route families #5839
• chore(docs): add OpenAPI bundler and Mintlify nav sync scripts #5838
• feat: adds missing endpoints to e2e api tests #5831
• dev

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

[coderabbitai]

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/openapi/schemas/management/governance.yaml (1)

918-939: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Regenerate the published OpenAPI bundle and align the Enterprise handlers. docs/docs.json publishes docs/openapi/openapi.json, which still documents total/page for both list responses. Regenerate it and confirm bifrost-enterprise/handlers/businessunits.go emits count, total_count, limit, and offset.

🤖 Prompt for 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.

In `@docs/openapi/schemas/management/governance.yaml` around lines 918 - 939,
Regenerate the published OpenAPI bundle so docs/docs.json and
docs/openapi/openapi.json reflect ListBusinessUnitsResponse fields count,
total_count, limit, and offset instead of total/page. Update the Enterprise
business-unit list handler around its response construction to emit those same
four fields, preserving the documented pagination values.

Source: Path instructions

🧹 Nitpick comments (3)

docs/openapi/schemas/management/users.yaml (1)

90-110: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Clarify the relationship between budget and budgets.

UserGovernanceRequest exposes both a single budget and a budgets array. The description does not state which field wins when a client sends both, or when each field applies. Add that rule to the description so API consumers can build a correct request.

♻️ Proposed clarification

     budget:
       $ref: './governance.yaml#/CreateBudgetRequest'
+      # document precedence, for example:
+      # description: Single budget. Ignored when `budgets` is present.
     budgets:
       type: array
+      description: Multiple budgets. Takes precedence over `budget` when both are sent.
       items:
         $ref: './governance.yaml#/CreateBudgetRequest'

🤖 Prompt for 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.

In `@docs/openapi/schemas/management/users.yaml` around lines 90 - 110, Update the
UserGovernanceRequest description to document how budget and budgets are used,
including which field takes precedence when both are provided and the conditions
under which each field applies.

docs/openapi/paths/management/users.yaml (2)

136-169: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a 400 response to getUserByEmail.

The email path parameter must be URL-encoded. The sibling operation getUserVirtualKeysByEmail at lines 87-134 documents 400 for a malformed value. Document the same response here so both email-based lookups describe identical error behavior.

♻️ Proposed change

     responses:
       '200':
         description: Successful response
         content:
           application/json:
             schema:
               $ref: '../../schemas/management/users.yaml#/UserObject'
+      '400':
+        $ref: '../../openapi.yaml#/components/responses/BadRequest'
       '404':
         $ref: '../../openapi.yaml#/components/responses/NotFound'

🤖 Prompt for 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.

In `@docs/openapi/paths/management/users.yaml` around lines 136 - 169, Add a 400
response to the getUserByEmail operation, matching the existing 400 response
reference and description used by the sibling getUserVirtualKeysByEmail
operation for malformed URL-encoded email path values.

---

4-10: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Extract the repeated Enterprise x-mint note into a shared definition. The identical x-mint block with the Enterprise tag and the same <Note> body is copied into every new operation across both files. No shared definition exists, so any wording or link change requires editing every copy.

• docs/openapi/paths/management/users.yaml#L4-L10: define the note once with a YAML anchor, for example x-mint: &enterprise-mint, then reference it with x-mint: *enterprise-mint in the other 15 operations in this file.
• docs/openapi/paths/management/businessunits.yaml#L14-L20: apply the same anchor-and-alias pattern to the 11 operations in this file, or move the note to a shared fragment that the bundler resolves.

Confirm first that the bundler preserves YAML anchors and aliases.

🤖 Prompt for 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.

In `@docs/openapi/paths/management/users.yaml` around lines 4 - 10, Confirm the
OpenAPI bundler preserves YAML anchors and aliases, then extract the repeated
Enterprise x-mint note in docs/openapi/paths/management/users.yaml lines 4-10
into an anchor and replace the other 15 operations there with its alias; apply
the same shared anchor-and-alias pattern to the 11 operations in
docs/openapi/paths/management/businessunits.yaml lines 14-20, or use a
bundler-resolved shared fragment, so the tag and note body have one source of
truth.

🤖 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.yaml`:
- Around line 950-958: Remove the stray
/api/users/{target_user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override
and /api/users/{target_user_id}/access-profiles/{profile_id}/virtual-keys
entries from the current path block in the OpenAPI definition. Keep the
/api/governance/... entries and the legacy definitions in the deprecated block
unchanged.

In `@docs/openapi/paths/management/accessprofiles.yaml`:
- Line 103: Update the AccessProfileDetailResponse path parameter from id to
profile_id, then regenerate docs/openapi/openapi.json from openapi.yaml so it
reflects the new governance access-profile paths and corrected route.

In `@docs/openapi/paths/management/businessunits.yaml`:
- Around line 14-32: Regenerate docs/openapi/openapi.json from the updated
business-unit OpenAPI definitions so the published catalog no longer includes
stale page and id parameters for business-unit operations. Verify the generated
catalog reflects the current offset-based definitions.

In `@docs/openapi/paths/management/governanceextensions.yaml`:
- Around line 161-176: Update the budget-override endpoint schema in the OpenAPI
path: replace the permissive request object under application/json with the
defined BudgetOverrideRequest schema, and replace the 200 response
MessageResponse reference with BudgetOverrideResponse. Preserve the existing
security and endpoint behavior while ensuring the documented request requires
amount and mode and the response exposes the effective limit.

In `@docs/openapi/paths/management/governancelegacy.yaml`:
- Line 1: Update the audit-log path mappings in governancelegacy.yaml so the
five legacy /api/audit-logs URLs point to their governancelegacy aliases, while
current operations are exposed under /api/governance/audit-logs... without
duplicate path keys. Then regenerate docs/openapi/openapi.json, leaving
docs/docs.json unchanged.
- Around line 3-6: Mark every legacy operation in the governance legacy OpenAPI
paths, including listVirtualKeyUsersLegacy, with deprecated: true while
preserving its existing successor and removal metadata, then regenerate the
published docs/openapi/openapi.json so it includes the materialized legacy
aliases and deprecation metadata.

In `@docs/openapi/paths/management/rbac.yaml`:
- Around line 341-355: Consolidate the role-assignment OpenAPI definition by
removing the unreferenced users-assign-role path or updating the existing
users.yaml#/users-role mapping to use it. Ensure the path parameter is named
user_id and role_id remains in the request body.

---

Outside diff comments:
In `@docs/openapi/schemas/management/governance.yaml`:
- Around line 918-939: Regenerate the published OpenAPI bundle so docs/docs.json
and docs/openapi/openapi.json reflect ListBusinessUnitsResponse fields count,
total_count, limit, and offset instead of total/page. Update the Enterprise
business-unit list handler around its response construction to emit those same
four fields, preserving the documented pagination values.

---

Nitpick comments:
In `@docs/openapi/paths/management/users.yaml`:
- Around line 136-169: Add a 400 response to the getUserByEmail operation,
matching the existing 400 response reference and description used by the sibling
getUserVirtualKeysByEmail operation for malformed URL-encoded email path values.
- Around line 4-10: Confirm the OpenAPI bundler preserves YAML anchors and
aliases, then extract the repeated Enterprise x-mint note in
docs/openapi/paths/management/users.yaml lines 4-10 into an anchor and replace
the other 15 operations there with its alias; apply the same shared
anchor-and-alias pattern to the 11 operations in
docs/openapi/paths/management/businessunits.yaml lines 14-20, or use a
bundler-resolved shared fragment, so the tag and note body have one source of
truth.

In `@docs/openapi/schemas/management/users.yaml`:
- Around line 90-110: Update the UserGovernanceRequest description to document
how budget and budgets are used, including which field takes precedence when
both are provided and the conditions under which each field applies.

🪄 Autofix

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: CHILL

Plan: Pro Plus

Run ID: ab3982a4-ae9f-41a3-80f3-b2e270e866a2

📥 Commits

Reviewing files that changed from the base of the PR and between a915552 and c9d55ea.

📒 Files selected for processing (13)

• docs/openapi/openapi.yaml
• docs/openapi/paths/management/accessprofiles.yaml
• docs/openapi/paths/management/auditlogs.yaml
• docs/openapi/paths/management/businessunits.yaml
• docs/openapi/paths/management/circuitbreaker.yaml
• docs/openapi/paths/management/governanceextensions.yaml
• docs/openapi/paths/management/governancelegacy.yaml
• docs/openapi/paths/management/mcptoolgroups.yaml
• docs/openapi/paths/management/rbac.yaml
• docs/openapi/paths/management/users.yaml
• docs/openapi/paths/management/vault.yaml
• docs/openapi/schemas/management/governance.yaml
• docs/openapi/schemas/management/users.yaml

[coderabbitai]

🧹 Nitpick comments (1)

docs/openapi/spec_invariants_test.py (1)

120-131: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Parse and resolve nested $ref values.

Lines 124-130 infer composition from raw YAML text. A comment or example can satisfy the string match. A nested reference can also target a missing operation while this test still treats its top-level fragment as used.

Load each fragment, collect actual $ref fields, and resolve their file and JSON Pointer targets. Derive composed only from resolved references.

Based on the stack context, docs/openapi/paths/management/governancelegacy.yaml contains nested references to governanceextensions.yaml that this loop currently scans as text.

🤖 Prompt for 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.

In `@docs/openapi/spec_invariants_test.py` around lines 120 - 131, Replace the
raw-text matching loop that builds composed in the fragment invariant test with
parsed YAML traversal of actual $ref fields, including nested mappings and
sequences. Resolve each reference’s target file and JSON Pointer, and add a
fragment to composed only when the resolved target exists and points to that
fragment. Preserve same-file and cross-file resolution while ignoring comments,
examples, and references to missing operations.

🤖 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.

Nitpick comments:
In `@docs/openapi/spec_invariants_test.py`:
- Around line 120-131: Replace the raw-text matching loop that builds composed
in the fragment invariant test with parsed YAML traversal of actual $ref fields,
including nested mappings and sequences. Resolve each reference’s target file
and JSON Pointer, and add a fragment to composed only when the resolved target
exists and points to that fragment. Preserve same-file and cross-file resolution
while ignoring comments, examples, and references to missing operations.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 65516b2d-b661-4653-aada-581f92bcc7f3

📥 Commits

Reviewing files that changed from the base of the PR and between c9d55ea and af72e02.

📒 Files selected for processing (6)

• docs/openapi/openapi.yaml
• docs/openapi/paths/management/accessprofiles.yaml
• docs/openapi/paths/management/governanceextensions.yaml
• docs/openapi/paths/management/governancelegacy.yaml
• docs/openapi/paths/management/rbac.yaml
• docs/openapi/spec_invariants_test.py

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/openapi/paths/management/rbac.yaml
• docs/openapi/paths/management/accessprofiles.yaml
• docs/openapi/paths/management/governancelegacy.yaml

[akshaydeo]

Merge activity

• Aug 11, 7:01 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 11, 7:04 AM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.