Skip to main content
Governance APIs now use the same /api/governance/* namespace in Bifrost Open Source and Bifrost Enterprise. Shared resources have one path and wire contract; Enterprise installs edition-specific handlers and adds relationship routes beneath the same resources.

​
Compatibility window

Enterprise legacy paths remain executable aliases for one complete GA release. Aliases execute the same handler directly, including mutating requests, and return:
  • Deprecation: true
  • Link: </api/governance/...>; rel="successor-version" (RFC 5829)
Alias use is also logged as structured telemetry. Migrate first-party and external clients during this window. The aliases are planned for removal in the following major release. To find alias traffic in your own clients, check responses for the presence of the Deprecation header and follow the successor-version link to the path you should call instead.
The former user-governance policy paths conflict with canonical User CRUD. They do not have compatibility aliases. Move POST /api/governance/users and PUT|DELETE /api/governance/users/{user_id} policy calls to /api/governance/users/{user_id}/governance when upgrading.

​
Endpoint mapping

Business Unit URLs were already under /api/governance/business-units; only OpenAPI path-parameter names were standardized.

​
Permissions

Canonical paths require the same RBAC resource and operation as the legacy alias they replace. Moving a client, script, or API key to a canonical path never requires regranting a permission, and no role loses access on upgrade. This parity is enforced by a test over the mapping table above, so it holds for every row. One deliberate exception: listing the virtual keys attached to a user is now gated on VirtualKeys rather than Users, on both the canonical /api/governance/users/{user_id}/virtual-keys and its legacy alias. This endpoint returns virtual-key material, and its siblings under /api/governance/virtual-keys/{vk_id}/users were already gated on VirtualKeys. Callers that read it with a Users-only role or API key need VirtualKeys:View added.
The user-level policy endpoints under /api/governance/users/{user_id}/governance keep the UserProvisioning resource they had when they lived on /api/governance/users. They have no compatibility alias, so grant parity here comes from the resource mapping rather than from an alias.

​
Pagination changes

Canonical Team and User list APIs use limit and zero-based offset, and return count, total_count, limit, and offset. Legacy aliases continue accepting page and preserve their former response envelopes during the compatibility window.
Audit logs are unchanged: /api/governance/audit-logs keeps the one-based page and limit parameters and the response envelope it served on /api/audit-logs. Only the path moved.

​
Team customer semantics

The canonical Team customer_id field retains the Open Source budget-hierarchy meaning. Enterprise many-to-many customer attachments use the relationship endpoints under /api/governance/teams/{team_id}/customers. Do not use the scalar customer_id field to represent Enterprise many-to-many membership.

​
Rollout checklist

  1. Upgrade to an Open Source transport version containing the typed governance route override seam.
  2. Upgrade Enterprise so it installs its Team read handler before Open Source route registration.
  3. Move API clients, scripts, Postman collections, and UI callers to canonical paths.
  4. Replace page with offset on canonical Team and User list requests.
  5. Grant VirtualKeys:View to any role or API key that reads a user’s virtual keys with only Users permission (see Permissions).
  6. Monitor deprecated-route telemetry until external alias traffic reaches zero.
  7. Remove aliases only in the following major release.