Governance

The governance block lets you seed all governance resources directly in config.json. On startup, Bifrost loads these into the configuration store. This is the recommended approach for GitOps workflows where governance state is managed as code.

In default split mode, file-backed governance resources seed or update the DB by hash while unrelated DB-only resources are preserved. With source_of_truth: "config.json", only governance sub-sections that are explicitly present in the file are authoritative. Omit a sub-section to leave DB-managed rows alone; set it to an empty array only when you intend to remove stored rows for that sub-section. See Source of Truth & Reconciliation.

Governance enforcement is always active in OSS - you do not need a plugin entry to enable it. To require a virtual key on every inference request, set client.enforce_auth_on_inference: true. This is the global default, but a more specific inference-auth flag such as governance.auth_config.disable_auth_on_inference overrides it; if no specific override is set, client.enforce_auth_on_inference applies.

Admin Authentication

Protect the Bifrost dashboard and management API with username/password auth:

{
  "governance": {
    "auth_config": {
      "is_enabled": true,
      "admin_username": "env.BIFROST_ADMIN_USERNAME",
      "admin_password": "env.BIFROST_ADMIN_PASSWORD",
      "disable_auth_on_inference": false
    }
  }
}

Field	Default	Description
`is_enabled`	`false`	Enable admin username/password auth
`admin_username`	-	Admin username (supports `env.` prefix)
`admin_password`	-	Admin password (supports `env.` prefix)
`disable_auth_on_inference`	`false`	Skip auth check on `/v1/*` inference routes

Virtual Keys

Virtual keys are issued to clients and act as scoped API tokens. Each key specifies which providers, models, and API keys the bearer is allowed to use.

{
  "governance": {
    "virtual_keys": [
      {
        "id": "vk-team-platform",
        "name": "platform-team",
        "value": "env.VK_PLATFORM_TEAM",
        "is_active": true,
        "provider_configs": [
          {
            "provider": "openai",
            "allowed_models": ["gpt-4o", "gpt-4o-mini"],
            "key_ids": ["*"],
            "weight": 1
          },
          {
            "provider": "anthropic",
            "allowed_models": ["*"],
            "key_ids": ["*"],
            "weight": 1
          }
        ]
      }
    ]
  }
}

Virtual Key Fields

Field	Required	Description
`id`	Yes	Unique virtual key ID (referenced by budgets / rate limits)
`name`	Yes	Human-readable name
`value`	No	The key token sent by clients (use `env.` prefix). Auto-generated if omitted
`is_active`	No	Default `true`. Set `false` to disable without deleting
`team_id`	No	Associate with a team (mutually exclusive with `customer_id`)
`customer_id`	No	Associate with a customer
`rate_limit_id`	No	Attach a rate limit
`calendar_aligned`	No	Snap budget resets to day/week/month/year boundaries
`provider_configs`	No	Allowed provider/model/key combinations (empty = deny all)

Provider Config Fields

Field	Required	Description
`provider`	Yes	Provider name (e.g. `"openai"`)
`allowed_models`	No	Model allow-list. `["*"]` = all models; `[]` = deny all
`key_ids`	No	Provider key names allowed for this VK. `["*"]` = all keys; `[]` = deny all. Use key `name` values (not UUIDs) in `config.json`
`weight`	No	Load-balancing weight when multiple provider configs are present
`rate_limit_id`	No	Attach a per-provider-config rate limit

Budgets

Budgets cap cumulative spend (in USD) for a virtual key or provider config over a rolling window:

{
  "governance": {
    "budgets": [
      {
        "id": "budget-platform-monthly",
        "max_limit": 500.00,
        "reset_duration": "1M",
        "virtual_key_id": "vk-team-platform"
      }
    ]
  }
}

Field	Required	Description
`id`	Yes	Unique budget ID
`max_limit`	Yes	Maximum spend in USD
`reset_duration`	Yes	Window length: `"30s"`, `"5m"`, `"1h"`, `"1d"`, `"1w"`, `"1M"`, `"1Y"`
`virtual_key_id`	No	Attach to a virtual key (mutually exclusive with `provider_config_id`)
`provider_config_id`	No	Attach to a provider config ID

Rate Limits

Rate limits cap requests or tokens over a rolling window:

{
  "governance": {
    "rate_limits": [
      {
        "id": "rl-platform-hourly",
        "request_max_limit": 1000,
        "request_reset_duration": "1h",
        "token_max_limit": 1000000,
        "token_reset_duration": "1h"
      }
    ]
  }
}

Field	Required	Description
`id`	Yes	Unique rate limit ID
`request_max_limit`	No	Maximum requests in window
`request_reset_duration`	No	Window for request counter
`token_max_limit`	No	Maximum tokens (input + output) in window
`token_reset_duration`	No	Window for token counter

Attach a rate limit to a virtual key via virtual_keys[].rate_limit_id, or to a provider config via virtual_keys[].provider_configs[].rate_limit_id.

Model Limits

governance.model_configs applies budgets and rate limits keyed on a model name, an optional provider, and a scope. This is the same data the Budget & Limits → Model Limits UI manages.

{
  "governance": {
    "model_configs": [
      {
        "id": "mc-gpt4o-global",
        "model_name": "gpt-4o",
        "provider": "openai",
        "budget_id": "budget-production",
        "rate_limit_id": "rl-platform-hourly"
      },
      {
        "id": "mc-openai-provider",
        "model_name": "*",
        "provider": "openai",
        "scope": "global",
        "budget_id": "budget-production"
      },
      {
        "id": "mc-vk-dev-toplevel",
        "model_name": "*",
        "scope": "virtual_key",
        "scope_id": "vk-dev-all",
        "budget_id": "budget-dev"
      }
    ]
  }
}

Field	Required	Description
`id`	Yes	Unique identifier
`model_name`	Yes	Model name, or `"*"` to match all models
`provider`	No	Provider name; omit to apply across all providers
`scope`	No	`"global"` (default, all traffic) or `"virtual_key"` (one VK)
`scope_id`	Conditional	Required when `scope` is `"virtual_key"` — the virtual key `id`
`budget_id`	No	References a `governance.budgets` entry
`rate_limit_id`	No	References a `governance.rate_limits` entry

Routing Rules

Routing rules dynamically select the provider and model for each request based on a CEL expression. They are evaluated in priority order before the request is dispatched.

{
  "governance": {
    "routing_rules": [
      {
        "id": "route-gpt4-to-azure",
        "name": "Redirect GPT-4o to Azure",
        "cel_expression": "request.model == 'gpt-4o'",
        "targets": [
          { "provider": "azure", "model": "gpt-4o", "weight": 1.0 }
        ]
      },
      {
        "id": "route-cost-split",
        "name": "Split traffic 70/30 between providers",
        "cel_expression": "true",
        "targets": [
          { "provider": "openai",    "weight": 0.7 },
          { "provider": "anthropic", "weight": 0.3 }
        ]
      }
    ]
  }
}

Rule Fields

Field	Required	Description
`id`	Yes	Unique rule ID
`name`	Yes	Human-readable name
`cel_expression`	No	CEL expression. `"true"` matches every request
`targets`	Yes	Weighted target list (weights must sum to `1.0`)
`enabled`	No	Default `true`
`priority`	No	Evaluation order within scope - lower numbers run first
`scope`	No	`"global"` (default), `"team"`, `"customer"`, `"virtual_key"`
`scope_id`	Conditional	Required when `scope` is not `"global"`
`chain_rule`	No	If `true`, re-evaluates the chain after this rule matches
`fallbacks`	No	Ordered fallback provider list if primary target fails

Target Fields

Field	Required	Description
`weight`	Yes	Fraction of traffic (all weights in a rule must sum to `1.0`)
`provider`	No	Target provider. Omit to keep the incoming request’s provider
`model`	No	Target model. Omit to keep the incoming request’s model
`key_id`	No	Pin a specific API key by name

Customers & Teams

Define organizational entities and attach budgets or rate limits to them:

{
  "governance": {
    "customers": [
      {
        "id": "customer-acme",
        "name": "Acme Corp",
        "budget_id": "budget-acme-monthly",
        "rate_limit_id": "rl-acme-hourly"
      }
    ],
    "teams": [
      {
        "id": "team-ml",
        "name": "ML Team",
        "customer_id": "customer-acme",
        "budget_id": "budget-team-ml"
      }
    ]
  }
}

Full Governance Example

{
  "$schema": "https://www.getbifrost.ai/schema",
  "encryption_key": "env.BIFROST_ENCRYPTION_KEY",

  "client": {
    "enforce_auth_on_inference": true
  },

  "governance": {
    "auth_config": {
      "is_enabled": true,
      "admin_username": "env.BIFROST_ADMIN_USERNAME",
      "admin_password": "env.BIFROST_ADMIN_PASSWORD"
    },

    "budgets": [
      {
        "id": "budget-platform",
        "max_limit": 1000.00,
        "reset_duration": "1M",
        "virtual_key_id": "vk-platform"
      }
    ],

    "rate_limits": [
      {
        "id": "rl-platform",
        "request_max_limit": 5000,
        "request_reset_duration": "1h",
        "token_max_limit": 5000000,
        "token_reset_duration": "1h"
      }
    ],

    "virtual_keys": [
      {
        "id": "vk-platform",
        "name": "platform-key",
        "value": "env.VK_PLATFORM",
        "is_active": true,
        "rate_limit_id": "rl-platform",
        "provider_configs": [
          {
            "provider": "openai",
            "allowed_models": ["*"],
            "key_ids": ["*"],
            "weight": 1
          }
        ]
      }
    ],

    "routing_rules": [
      {
        "id": "fallback-to-anthropic",
        "name": "Fallback on error",
        "cel_expression": "true",
        "targets": [{ "provider": "openai", "weight": 1.0 }],
        "fallbacks": ["anthropic"]
      }
    ]
  },

  "providers": {
    "openai": {
      "keys": [{ "name": "openai-primary", "value": "env.OPENAI_API_KEY", "models": ["*"], "weight": 1.0 }]
    },
    "anthropic": {
      "keys": [{ "name": "anthropic-primary", "value": "env.ANTHROPIC_API_KEY", "models": ["*"], "weight": 1.0 }]
    }
  },

  "config_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "env.PG_HOST",
      "port": "5432",
      "user": "env.PG_USER",
      "password": "env.PG_PASSWORD",
      "db_name": "bifrost"
    }
  }
}

Platform specific guides

Config as Code

Enterprise Deployment

Common setup instructions

Admin Authentication

Virtual Keys

Virtual Key Fields

Provider Config Fields

Budgets

Rate Limits

Model Limits

Routing Rules

Rule Fields

Target Fields

Customers & Teams

Full Governance Example

​Admin Authentication

​Virtual Keys

​Virtual Key Fields

​Provider Config Fields

​Budgets

​Rate Limits

​Model Limits

​Routing Rules

​Rule Fields

​Target Fields

​Customers & Teams

​Full Governance Example

Admin Authentication

Virtual Keys

Virtual Key Fields

Provider Config Fields

Budgets

Rate Limits

Model Limits

Routing Rules

Rule Fields

Target Fields

Customers & Teams

Full Governance Example