Virtual Keys

Overview

Virtual Keys are the primary governance entity in Bifrost. Users and applications authenticate using the given headers to access virtual keys and get specific access permissions, budgets, and rate limits. Allowed Headers:

x-bf-vk - Virtual key header, eg. sk-bf-*
Authorization - Authorization header, eg. Bearer sk-bf-* (OpenAI style)
x-api-key - API key header, eg. sk-bf-* (Anthropic style)
x-goog-api-key - API key header, eg. sk-bf-* (Google Gemini style)
api-key - API key header, eg. sk-bf-* (Azure OpenAI style)

Old virtual keys(without sk-bf-* prefix) are only supported by x-bf-vk header.

Enterprise: IdP tokens are also accepted. Virtual keys remain the standard way to authenticate. On Bifrost Enterprise with SSO configured, you can also authenticate with a token issued by your identity provider: Authorization: Bearer <idp-token>. Bifrost validates the token and attributes the request to that user, applying their access profile, budgets, and rate limits. Use the Authorization header for IdP tokens; the other headers above carry virtual keys only. See Setting up auth for details.

Key Features:

Access Control - Model and provider filtering
Cost Management - Independent budgets (checked along with team/customer budgets if attached)
Budget Overrides - Temporarily add spending capacity without changing the base budget
Rate Limiting - Token and request-based throttling (VK-level only)
Key Restrictions - Limit VK to specific provider API keys (if configured, VK can only use those keys)
Exclusive Attachment - Belongs to either one team OR one customer OR neither (mutually exclusive). In Enterprise, a key can also belong to a business unit or a user, still only one owner
Active/Inactive Status - Enable/disable access instantly

Configuration

Web UI
API
config.json

Go to Virtual Keys
Click on Add Virtual Key button

Budget Settings:

Max Limit: Dollar amount (e.g., 10.50)
Reset Duration: 1m, 1h, 1d, 1w, 1M, 1Q, 1Y
Calendar aligned (optional): When enabled, the budget resets at calendar boundaries in UTC (day/week/month/quarter/year) instead of on a rolling window. Only applies to day/week/month/quarter/year periods. See Budget and Limits.

Rate Limits:

Token Limit: Max tokens per period
Request Limit: Max requests per period
Reset Duration: Reset frequency for each limit

Associations:

Team: Assign to existing team (mutually exclusive with customer)
Customer: Assign to existing customer (mutually exclusive with team)

Expiry (optional): Pick Never, a preset (30 min to 7 days), or a custom date and time. See Key Expiry.Content logging (optional): Inherit gateway setting (default), Off for this key, or On for this key. See Content logging per key.

Click Create Virtual Key

Create Virtual Key (attached to team):

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team API",
    "description": "Main API key for engineering team",
    "provider_configs": [
      {
        "provider": "openai",
        "weight": 0.5,
        "allowed_models": ["gpt-4o-mini"],
        "key_ids": ["8c52039e-38c6-48b2-8016-0bd884b7befb"]
      },
      {
        "provider": "anthropic",
        "weight": 0.5,
        "allowed_models": ["claude-3-sonnet-20240229"],
        "key_ids": ["*"]
      }
    ],
    "team_id": "team-eng-001",
    "budgets": [
      {
        "max_limit": 100.00,
        "reset_duration": "1M"
      }
    ],
    "rate_limit": {
      "token_max_limit": 10000,
      "token_reset_duration": "1h",
      "request_max_limit": 100,
      "request_reset_duration": "1m"
    },
    "is_active": true
  }'

Create Virtual Key (directly attached to customer):

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Executive API Key",
    "description": "Direct customer-level API access",
    "provider_configs": [
      {
        "provider": "openai",
        "weight": 0.5,
        "allowed_models": ["gpt-4o"],
        "key_ids": ["*"]
      },
      {
        "provider": "anthropic",
        "weight": 0.5,
        "allowed_models": ["claude-3-opus-20240229"],
        "key_ids": ["*"]
      }
    ],
    "customer_id": "customer-acme-corp",
    "budgets": [
      {
        "max_limit": 500.00,
        "reset_duration": "1M"
      }
    ],
    "is_active": true
  }'

Note:

team_id and customer_id are mutually exclusive - a VK can only belong to one team OR one customer, not both.

key_ids belongs inside each provider_configs entry and restricts that provider to the listed API key IDs. Use ["*"] to allow all keys for that provider. An empty array [] or an omitted field denies all keys.

budgets is always an array, both at the Virtual Key level and inside a provider config. The old singular budget and budget_id request fields are ignored. See the v1.5.0 migration guide for the before-and-after shapes.

Update Virtual Key:

curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id} \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "budgets": [
      {
        "max_limit": 150.00,
        "reset_duration": "1M"
      }
    ]
  }'

See Create virtual key and Update virtual key for the complete request and response schemas.Get Virtual Keys:

# List all virtual keys
curl http://localhost:8080/api/governance/virtual-keys

# Get specific virtual key
curl http://localhost:8080/api/governance/virtual-keys/{vk_id}

Delete Virtual Key:

curl -X DELETE http://localhost:8080/api/governance/virtual-keys/{vk_id}

{
  "client": {
    "enforce_auth_on_inference": true
  },
  "governance": {
    "virtual_keys": [
      {
        "id": "vk-001",
        "name": "Engineering Team API",
        "value": "sk-bf-*",
        "description": "Main API key for engineering team",
        "is_active": true,
        "provider_configs": [
          {
            "provider": "openai",
            "weight": 0.5,
            "allowed_models": ["gpt-4o-mini"],
            "key_ids": ["openai-primary"]
          },
          {
            "provider": "anthropic",
            "weight": 0.5,
            "allowed_models": ["claude-3-sonnet-20240229"],
            "key_ids": ["*"]
          }
        ],
        "team_id": "team-eng-001",
        "rate_limit_id": "rate-limit-eng-vk"
      },
      {
        "id": "vk-002",
        "name": "Executive API Key", 
        "value": "vk-executive-direct",
        "description": "Direct customer-level API access",
        "is_active": true,
        "provider_configs": [
          {
            "provider": "openai",
            "weight": 0.5,
            "allowed_models": ["gpt-4o"],
            "key_ids": ["*"]
          },
          {
            "provider": "anthropic",
            "weight": 0.5,
            "allowed_models": ["claude-3-opus-20240229"],
            "key_ids": ["*"]
          }
        ],
        "customer_id": "customer-acme-corp"
      }
    ],
    "budgets": [
      {
        "id": "budget-eng-vk",
        "virtual_key_id": "vk-001",
        "max_limit": 100.00,
        "reset_duration": "1M",
        "current_usage": 0.0,
        "last_reset": "2025-01-01T00:00:00Z"
      },
      {
        "id": "budget-exec-vk",
        "virtual_key_id": "vk-002",
        "max_limit": 500.00,
        "reset_duration": "1M",
        "current_usage": 0.0,
        "last_reset": "2025-01-01T00:00:00Z"
      }
    ],
    "rate_limits": [
      {
        "id": "rate-limit-eng-vk", 
        "token_max_limit": 10000,
        "token_reset_duration": "1h",
        "token_current_usage": 0,
        "token_last_reset": "2025-01-01T00:00:00Z",
        "request_max_limit": 100,
        "request_reset_duration": "1m",
        "request_current_usage": 0,
        "request_last_reset": "2025-01-01T00:00:00Z"
      }
    ]
  }
}

Content logging per key

Each virtual key can decide whether the content of its requests and responses is stored. The disable_content_logging field is tri-state:

omitted or null: inherit client.disable_content_logging
true: content is not stored in the log store for this key’s traffic (an allowed x-bf-disable-content-logging: false header can still re-enable it for one request), and OpenTelemetry export is stripped of content too
false: content is stored for this key’s traffic even when the client setting is true

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "disable_content_logging": true,
    "provider_configs": [{ "provider": "openai", "allowed_models": ["*"], "key_ids": ["*"] }]
  }'

# Clear the decision back to inherit
curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id} \
  -H "Content-Type: application/json" \
  -d '{ "disable_content_logging": null }'

Precedence is client setting, then the key, then the x-bf-disable-content-logging header when per-request overrides are allowed. See Content Logging for how each layer treats the log store and observability connectors.

Provider access

By default a virtual key is deny-by-default for providers: it can only use providers listed in provider_configs. An empty provider_configs blocks every provider. Set allow_all_providers to true to grant the key access to every configured provider, including providers added later, without listing each one.

Web UI
API
config.json

In the Provider Configurations section of the virtual key form, turn on the Allow all providers toggle. Every configured provider is listed as a row, so you can optionally set per-provider budgets, rate limits, or model/key restrictions on any of them. When the toggle is off, provider access is deny-by-default: only providers listed in provider_configs are allowed, and providers added later are denied.

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Providers Key",
    "allow_all_providers": true,
    "team_id": "team-eng-001",
    "is_active": true
  }'

{
  "governance": {
    "virtual_keys": [
      {
        "id": "vk-all",
        "name": "All Providers Key",
        "value": "sk-bf-*",
        "is_active": true,
        "allow_all_providers": true
      }
    ]
  }
}

allow_all_providers coexists with provider_configs. When it is on, a provider that also has a provider_configs entry still has that entry’s model allow/blacklist, budgets, rate limits, and key selection applied; providers without an entry get all models, all keys, and no per-provider limits. This lets you allow everything while still capping or restricting specific providers.

How access is resolved

Access depends on the allow_all_providers value and whether the provider has a provider_configs entry:

Flag value	Listed in `provider_configs`	Not listed
`false` (default)	Allowed, subject to that entry’s models, keys, budgets, and rate limits	Denied
`true`	Allowed, subject to that entry’s models, keys, budgets, and rate limits	Allowed with all models, all keys, and no per-provider limits

When allow_all_providers is true:

A listed provider’s allowed_models and blacklisted_models still apply. Allow-all never widens an allowlist: a model outside a listed provider’s allowed_models stays denied, and a model in its blacklisted_models stays denied.
An entry in either list that starts with regex: is an RE2 pattern instead of a name. It must match the whole model name and is case-insensitive, so "allowed_models": ["gpt-4o", "regex:^claude-3-.*"] allows gpt-4o and every claude-3- model, and "blacklisted_models": ["regex:.*-preview$"] blocks every preview. A pattern that is empty, *, or does not compile is refused with 400. Patterns in blacklisted_models win over allowed_models, and patterns are never listed as models.
A listed provider’s budgets, rate limits, and key_ids selection still apply. Allow-all does not lift per-provider limits on providers you have configured.
Only providers with no provider_configs entry get the open treatment (all models, all keys, no limits).
Providers added to Bifrost after the key was created are treated as unlisted, so they are allowed automatically without editing the key.

allow_all_providers defaults to false. When it is false, provider access stays deny-by-default via provider_configs.

Batches defined by an uploaded file

A batch created from input_file_id or input_blob names its models inside the uploaded input, which Bifrost does not read. When a key restricts models on the provider (an allowed_models list other than *, or any blacklisted_models), such batches are checked against what the provider actually runs:

OpenAI and Azure run the models named in each input row and ignore the model on the batch request, so creating a file- or blob-based batch requires a key that allows every model of that provider. Otherwise the request is refused with 403 (model_blocked), even if an allowed model is supplied.
Gemini, Vertex, and Bedrock run the model named on the batch request, so that model must be supplied and allowed by the key.

A custom provider is held to the rule of its base provider type, since it runs that provider’s batch API. A request that names a file or blob and inline requests together is refused with 400: no provider runs inline requests beside a file, so the batch’s work must be named once. Inline batches (requests) are checked per item and are unaffected, as are keys that allow every model of the provider.

Passthrough requests

A passthrough route forwards the request body as the provider reads it. When a key restricts models on the provider, every model the body names is checked: the model of a JSON object body, or the model of each task in a task array (Runware). A passthrough request that names no model anywhere, neither in its path nor in its body, is refused with 403 (model_blocked) under such a key, since the provider would still run a model the key never allowed. Keys that allow every model of the provider forward every passthrough body as before.

User Groups

Teams

Teams provide organizational grouping for virtual keys with department-level budget management. Teams can belong to one customer and have their own independent budget allocation. Key Features:

Organizational Structure - Group multiple virtual keys
Independent Budgets - Department-level cost control (separate from customer budgets)
Customer Association - Can belong to one customer (optional)
Rate Limit - A team can have one rate limit of its own, checked alongside its keys’ rate limits

Configuration

Web UI
API
config.json

Go to Governance → Teams
Click on Add Team button

Fill the form and click on Create Team button

Assign Virtual Keys to Team
- Go to Virtual Keys page
- Edit the virtual key and assign it to the team
- Click on Save button

Create Team:

curl -X POST http://localhost:8080/api/governance/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "customer_id": "customer-acme-corp",
    "budgets": [
      {
        "max_limit": 500.00,
        "reset_duration": "1M"
      }
    ]
  }'

Update Team:

curl -X PUT http://localhost:8080/api/governance/teams/{team_id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Engineering Team",
    "budgets": [
      {
        "max_limit": 750.00,
        "reset_duration": "1M"
      }
    ]
  }'

Get Teams:

# List all teams
curl http://localhost:8080/api/governance/teams

# Get specific team
curl http://localhost:8080/api/governance/teams/{team_id}

Delete Team:

curl -X DELETE http://localhost:8080/api/governance/teams/{team_id}

{
  "governance": {
    "teams": [
      {
        "id": "team-eng-001",
        "name": "Engineering Team",
        "customer_id": "customer-acme-corp"
      },
      {
        "id": "team-sales-001", 
        "name": "Sales Team",
        "customer_id": "customer-acme-corp"
      }
    ],
    "budgets": [
      {
        "id": "budget-team-eng",
        "max_limit": 500.00,
        "reset_duration": "1M",
        "current_usage": 0.0,
        "last_reset": "2025-01-01T00:00:00Z",
        "team_id": "team-eng-001"
      },
      {
        "id": "budget-team-sales",
        "max_limit": 250.00,
        "reset_duration": "1M", 
        "current_usage": 0.0,
        "last_reset": "2025-01-01T00:00:00Z",
        "team_id": "team-sales-001"
      }
    ]
  }
}

Team budgets are owned from the budget side: set team_id on each entry in governance.budgets. Do not add budget_id to a team. A team can own multiple budgets as long as their reset durations are unique.

Customers

Customers represent the highest level in the governance hierarchy, typically corresponding to organizations or major business units. They provide top-level budget control and organizational structure. Key Features:

Top-Level Organization - Highest hierarchy level
Independent Budgets - Organization-wide cost control (separate from team/VK budgets)
Team Management - Contains multiple teams and direct VKs
Rate Limit - A customer can have one rate limit of its own, checked alongside its teams’ and keys’ rate limits

Configuration

Web UI
API
config.json

Go to Governance → Customers
Click on Add Customer button

Fill the form and click on Create Customer button

Assign Teams to Customer
- Go to Teams page
- Edit the team and assign it to the customer
- Click on Save button
Assign Virtual Keys to Customer
- Go to Virtual Keys page
- Edit the virtual key and assign it to the customer
- Click on Save button

Create Customer:

curl -X POST http://localhost:8080/api/governance/customers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "budget": {
      "max_limit": 2000.00,
      "reset_duration": "1M"
    }
  }'

Update Customer:

curl -X PUT http://localhost:8080/api/governance/customers/{customer_id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Updated)",
    "budget": {
      "max_limit": 2500.00,
      "reset_duration": "1M"
    }
  }'

Get Customers:

# List all customers
curl http://localhost:8080/api/governance/customers

# Get specific customer
curl http://localhost:8080/api/governance/customers/{customer_id}

Delete Customer:

curl -X DELETE http://localhost:8080/api/governance/customers/{customer_id}

{
  "governance": {
    "customers": [
      {
        "id": "customer-acme-corp",
        "name": "Acme Corporation",
        "budget_id": "budget-customer-acme"
      },
      {
        "id": "customer-beta-inc",
        "name": "Beta Inc",
        "budget_id": "budget-customer-beta"
      }
    ],
    "budgets": [
      {
        "id": "budget-customer-acme",
        "max_limit": 2000.00,
        "reset_duration": "1M",
        "current_usage": 0.0,
        "last_reset": "2025-01-01T00:00:00Z"
      },
      {
        "id": "budget-customer-beta",
        "max_limit": 1500.00,
        "reset_duration": "1M",
        "current_usage": 0.0,
        "last_reset": "2025-01-01T00:00:00Z"
      }
    ]
  }
}

Features

Budget and Limits - Enterprise-grade budget management and cost control and rate limiting using virtual keys
Routing - Route requests to the appropriate providers/models and restrict api keys using virtual keys
MCP Tool Filtering - Manage MCP clients/tools for virtual keys

Usage

Budget Overrides

Budget overrides add temporary spending capacity to an existing virtual-key budget without changing its base limit, current usage, or reset schedule. While an override is active, Bifrost calculates the effective limit as:

Effective limit = Base budget + Override amount

For example, adding a $100 override to a $1,000 budget raises its effective limit to $1,100.

Go to Virtual Keys, open a virtual key, and scroll to Budget Information.
Click Add override on the budget you want to increase.

Enter the Additional budget, then choose a duration:
- For a number of reset cycles: Enter one or more cycles. The current cycle counts as the first cycle, and the dialog shows the date and time until which the override is expected to remain valid.
- Until removed: Keep the override active across resets until it is removed manually.

Configure the budget override amount and duration

Click Add override. The budget card displays the effective limit, its base and override amounts, and either the remaining reset cycles or until removed.

Virtual-key budget with an active override

To change or remove an active override, click Edit override on the budget card.

Overrides are available after a budget has been created. Budgets inherited from an enterprise access profile must be overridden from that access profile instead of from the virtual key.

Managing overrides via API

Two endpoints manage the override on a single virtual-key budget. Both take the virtual key ID and the ID of a budget that key owns, and both return the persisted budget alongside its effective_max_limit. Grant extra spend for a fixed number of reset cycles:

curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id}/budgets/{budget_id}/override \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.0,
    "mode": "cycles",
    "cycles": 2
  }'

The current cycle counts as the first, so "cycles": 2 covers the rest of this window plus the next one. Use "mode": "forever" (with no cycles) to keep the override active until it is removed:

curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id}/budgets/{budget_id}/override \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.0,
    "mode": "forever"
  }'

Response

{
  "budget": {
    "id": "budget-vk-alpha",
    "max_limit": 1000.0,
    "reset_duration": "1M",
    "current_usage": 240.5,
    "override_amount": 100.0,
    "override_mode": "forever",
    "last_reset": "2025-01-01T00:00:00Z"
  },
  "effective_max_limit": 1100.0
}

A PUT always replaces the existing override rather than adding to it, so re-sending an override with a new amount or mode is the way to change one. Remove it with a DELETE, which restores enforcement against the base max_limit:

curl -X DELETE http://localhost:8080/api/governance/virtual-keys/{vk_id}/budgets/{budget_id}/override

Notes on behavior:

The override never changes max_limit, current_usage, or the reset schedule — only the limit that usage is enforced against.
amount must be greater than 0. In cycles mode, cycles must be greater than 0; in forever mode it must be omitted.
A finite grant is anchored to the budget’s current reset window, so remaining cycles are derived from that grant on every reset. Each node in a cluster computes the same count, and a config reload cannot hand back a cycle that was already spent.
A cycles override clears itself once every granted window has closed; DELETE clears one at any time and cannot be undone.

For the full request and response schema, see Set virtual key budget override and Remove virtual key budget override in the API Reference.

Making Virtual Keys Mandatory

All governance-enabled requests must include the virtual key header:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-vk: sk-bf-*" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

By default governance is optional, meaning that if the virtual key header is not present, the request will be allowed but without any governance checks/routing. But you can make it mandatory by enforcing the virtual key header.

Web UI
API
config.json

Go to Settings → Security.
Turn on Enable Auth on Inference. In OSS, this toggle is labeled Enforce Virtual Keys on Inference.
Click Save Changes.

curl -X PUT http://localhost:8080/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "client_config": {
      "enforce_auth_on_inference": true
    }
  }'

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

In OSS, enabling this setting makes a valid virtual key mandatory for every inference request. Requests without one are rejected.

Key Expiry

Virtual keys can optionally carry an expiry timestamp. Once the expiry passes, requests using the key are rejected with a 403 and the reason Virtual key has expired. By default the key is not deleted or deactivated, so it stays visible for auditing and can be restored at any time.

No expiry by default — keys without expires_at never expire.
Fail closed — both LLM inference and MCP tool execution are blocked once the key expires.
Inactive wins — a key that is both inactive and expired is rejected as inactive.
Restore anytime — extend the expiry to a future timestamp or clear it; access resumes immediately.
Delete after expire (optional) — a cleanup job that runs once a day removes expired keys. Turn it on for the whole workspace under Settings → Security → Delete Expired Virtual Keys (config.json: client.delete_expired_virtual_keys, default false), or per key with the Delete after expire switch (API: delete_after_expire). A key with no value of its own follows the workspace setting; true or false on the key wins over it. Each run that deletes at least one key posts a notification listing the removed keys; runs that find nothing stay silent. The per-key value needs an expiry: setting it without one returns 400, and clearing the expiry resets the key to inherit.

Web UI
API
config.json

Go to Virtual Keys and create or edit a key
In the Expiry section, pick Never, a preset (30 min, 1 hour, 24 hours, 7 days), or choose a custom date and time from the calendar
Optionally flip Delete after expire. The switch starts at the workspace setting from Settings → Security; leave it there to follow that setting, or flip it to decide for this key

Expired keys show an Expired badge in the virtual keys table, with auto-delete appended when the key will be cleaned up, whether by its own setting or the workspace default.

Create with expiry:

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contractor API Key",
    "provider_configs": [
      {
        "provider": "openai",
        "allowed_models": ["gpt-4o-mini"],
        "key_ids": ["*"]
      }
    ],
    "expires_at": "2027-01-01T00:00:00Z",
    "delete_after_expire": true
  }'

Set or extend expiry on an existing key:

curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id} \
  -H "Content-Type: application/json" \
  -d '{"expires_at": "2027-02-01T00:00:00Z"}'

Clear expiry (key never expires again):

curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id} \
  -H "Content-Type: application/json" \
  -d '{"expires_at": ""}'

Timestamps must be RFC3339 and in the future; otherwise the API returns 400. On update, omitting expires_at leaves the current expiry unchanged. delete_after_expire can be sent on create or update: omit it to follow client.delete_expired_virtual_keys, send true or false to decide for this key, or send null on update to go back to inheriting. Any value is rejected with 400 when the key has no expiry.Expired key rejection:

{
  "type": "access_blocked",
  "status_code": 403,
  "error": {
    "message": "virtual key has expired"
  }
}

{
  "governance": {
    "virtual_keys": [
      {
        "id": "vk-contractor",
        "name": "Contractor API Key",
        "value": "sk-bf-*",
        "provider_configs": [
          {
            "provider": "openai",
            "allowed_models": ["gpt-4o-mini"],
            "key_ids": ["*"]
          }
        ],
        "expires_at": "2027-01-01T00:00:00Z"
      }
    ]
  }
}

For config-managed virtual keys the file is the source of truth: removing expires_at from the file clears the expiry on the next sync.

Authentication and Virtual Keys

Virtual keys and HTTP authentication are independent layers that can work together:

Layer	Purpose	Headers
Authentication	Validates user identity	`Authorization: Basic/Bearer <credentials>`, or on Enterprise, `Authorization: Bearer <idp-token>`
Virtual Keys	Request routing and governance	`x-bf-vk`, `Authorization`¹, `x-api-key`, `x-goog-api-key`

When disable_auth_on_inference: true (auth disabled): Virtual keys can be passed via any supported header without additional authentication:

# Using x-bf-vk header
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-vk: <VIRTUAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

# Using Authorization header (OpenAI style)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer <VIRTUAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

Listing models with a virtual key

When you call GET /v1/models with a virtual key, Bifrost only lists (and only queries) providers that are allowed by that virtual key. This avoids unnecessary “provider not allowed” errors in logs and keeps error-rate metrics meaningful. A key with allow_all_providers enabled lists and queries every configured provider.

# Lists models across providers allowed by the virtual key
curl -sS "http://localhost:8080/v1/models" \
  -H "x-bf-vk: <VIRTUAL_KEY>"

If you specify a provider explicitly via ?provider=..., that provider must still be allowed by the virtual key or the request will be rejected:

# If "anthropic" is not configured/allowed on this virtual key, this returns 403
curl -sS "http://localhost:8080/v1/models?provider=anthropic" \
  -H "x-bf-vk: <VIRTUAL_KEY>"

When disable_auth_on_inference: false (auth enabled): You must provide both authentication credentials AND the virtual key. Use x-bf-vk for the virtual key since the Authorization header is used for authentication:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Basic <base64-credentials>" \
  -H "x-bf-vk: <VIRTUAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

Configuring disable_auth_on_inference:

Web UI
API
config.json

Go to Config → Security
Toggle Disable Auth on Inference to enable/disable

curl -X PUT http://localhost:8080/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "auth_config": {
      "disable_auth_on_inference": true
    }
  }'

{
  "auth_config": {
    "is_enabled": true,
    "disable_auth_on_inference": true
  }
}

Error Responses

type is a top-level field, beside status_code, and error carries only the message. A client branching on the refusal reads type, not error.type.

Authentication Required (401), when no credential was presented and virtual keys are mandatory

{
  "type": "virtual_key_required",
  "status_code": 401,
  "error": {
    "message": "virtual key is required. Provide a virtual key via the x-bf-vk header."
  }
}

Inactive or Expired (403), when the credential is real but may not be used

{
  "type": "access_blocked",
  "status_code": 403,
  "error": {
    "message": "virtual key is inactive"
  }
}

A key that is both inactive and expired reports is inactive: the check runs in that order and answers on the first that matches. The same type and shape covers an expired key (virtual key has expired) and an access profile that is inactive or expired.

Rate Limit Exceeded (429): rate_limited, or token_limited / request_limited for the dimension that ran out

{
  "type": "token_limited",
  "status_code": 429,
  "error": {
    "message": "Rate limit exceeded: rate limit violated for vk_model_config * : [token limit exceeded (1500/1000, resets every 1h)]"
  }
}

Budget Exceeded (402)

{
  "type": "budget_exceeded",
  "status_code": 402,
  "error": {
    "message": "Budget exceeded: vk_model_config * budget exceeded: 105.5000 >= 100.0000 dollars"
  }
}

The name after the holder kind is what ran out, so a refusal says which tier stopped the request rather than only that something did.

Model Not Allowed (403)

{
  "type": "model_blocked",
  "status_code": 403,
  "error": {
    "message": "Model 'gpt-4o' is not allowed for virtual key 'my-key'"
  }
}

Provider Not Allowed (403)

{
  "type": "provider_blocked",
  "status_code": 403,
  "error": {
    "message": "Provider 'anthropic' is not allowed for virtual key 'my-key'"
  }
}

MCP Tool Not Allowed (403)

{
  "type": "mcp_tool_blocked",
  "status_code": 403,
  "error": {
    "message": "MCP tool 'filesystem-write_file' is not allowed for virtual key 'my-key'"
  }
}

Authorization can carry virtual keys only when auth is disabled (disable_auth_on_inference: true). When auth is enabled, Authorization is consumed by authentication and cannot be used for virtual keys. ↩

Overview

Quick Start

Release Cadence

Migration Guides

Migrate from other Gateway

SDK Integrations

Providers & Guides

MCP Gateway

Agent Gateway

Custom plugins

Open Source Features

Overview

Configuration

Content logging per key

Provider access

How access is resolved

Batches defined by an uploaded file

Passthrough requests

User Groups

Teams

Customers

Features

Usage

Budget Overrides

Managing overrides via API

Making Virtual Keys Mandatory

Key Expiry

Authentication and Virtual Keys

Listing models with a virtual key

Error Responses

​Overview

​Configuration

​Content logging per key

​Provider access

​How access is resolved

​Batches defined by an uploaded file

​Passthrough requests

​User Groups

​Teams

​Customers

​Features

​Usage

​Budget Overrides

​Managing overrides via API

​Making Virtual Keys Mandatory

​Key Expiry

​Authentication and Virtual Keys

​Listing models with a virtual key

​Error Responses

Footnotes

Overview

Configuration

Content logging per key

Provider access

How access is resolved

Batches defined by an uploaded file

Passthrough requests

User Groups

Teams

Customers

Features

Usage

Budget Overrides

Managing overrides via API

Making Virtual Keys Mandatory

Key Expiry

Authentication and Virtual Keys

Listing models with a virtual key

Error Responses