Skip to main content

​
Overview

Virtual Keys are the primary governance entity in Bifrost. Users and applications authenticate using the x-bf-vk header (not the Authorization header), which maps to specific access permissions, budgets, and rate limits. Key Features:
  • Access Control - Model and provider filtering
  • Cost Management - Independent budgets (checked along with team/customer budgets if attached)
  • 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)
  • Active/Inactive Status - Enable/disable access instantly

​
Configuration

  • Web UI
  • API
  • config.json
  1. Go to Virtual Keys
  2. Click on Add Virtual Key button Virtual Key Creation
Budget Settings:
  • Max Limit: Dollar amount (e.g., 10.50)
  • Reset Duration: 1m, 1h, 1d, 1w, 1M
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)
  1. Click Create Virtual Key

​
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)
  • No Rate Limits - Teams cannot have rate limits (VK-level only)
Configuration
  • Web UI
  • API
  • config.json
  1. Go to Users & Groups → Teams
  2. Click on Add Team button Team Creation
Fill the form and click on Create Team button
  1. Assign Virtual Keys to Team
    • Go to Virtual Keys page
    • Edit the virtual key and assign it to the team
    • Click on Save button

​
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
  • No Rate Limits - Customers cannot have rate limits (VK-level only)
Configuration
  • Web UI
  • API
  • config.json
  1. Go to Users & Groups → Customers
  2. Click on Add Customer button Customer Creation
Fill the form and click on Create Customer button
  1. Assign Teams to Customer
    • Go to Teams page
    • Edit the team and assign it to the customer
    • Click on Save button
  2. Assign Virtual Keys to Customer
    • Go to Virtual Keys page
    • Edit the virtual key and assign it to the customer
    • Click on Save button

​
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

​
Required Header

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: vk-engineering-main" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
By default governance is optional, meaning that if the x-bf-vk header is not present, the request will be allowed but without any governance checks/routing. But you can make it mandatory by enforcing the governance header.
  • Web UI
  • API
  • config.json
  1. Go to Client → Governance
  2. Check the Enforce Governance Header checkbox
When the governance header is enforced, the request will be rejected if the x-bf-vk header is not present.

​
Optional Audit Headers

Include additional headers for enhanced tracking and audit trails: 
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-vk: vk-engineering-main" \
  -H "x-bf-team: team-eng-001" \
  -H "x-bf-customer: customer-acme-corp" \
  -H "x-bf-user-id: user-alice" \
  -d '{
    "model": "gpt-4o-mini", 
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
Header Definitions:
  • x-bf-vk - Required virtual key for access control
  • x-bf-team - Optional team identifier for audit trails
  • x-bf-customer - Optional customer identifier for audit trails
  • x-bf-user-id - Optional user identifier for detailed tracking

​
Error Responses

  • Virtual Key Not Found (400)
{
  "error": {
    "type": "virtual_key_required",
    "message": "x-bf-vk header is missing"
  }
}
  • Virtual Key Blocked (403)
{
  "error": {
    "type": "virtual_key_blocked", 
    "message": "Virtual key is inactive"
  }
}
  • Rate Limit Exceeded (429)
{
  "error": {
    "type": "rate_limited",
    "message": "Rate limits exceeded: [token limit exceeded (1500/1000, resets every 1h)]"
  }
}
  • Token Limit Exceeded (429)
{
  "error": {
    "type": "token_limited",
    "message": "Rate limits exceeded: [token limit exceeded (1500/1000, resets every 1h)]"
  }
}
  • Request Limit Exceeded (429)
{
  "error": {
    "type": "request_limited", 
    "message": "Rate limits exceeded: [request limit exceeded (101/100, resets every 1m)]"
  }
}
  • Budget Exceeded (402)
{
  "error": {
    "type": "budget_exceeded",
    "message": "Budget check failed: VK budget exceeded: 105.50 > 100.00 dollars"
  }
}
  • Model Not Allowed (403)
{
  "error": {
    "type": "model_blocked",
    "message": "Model 'gpt-4o' is not allowed for this virtual key"
  }
}
  • Provider Not Allowed (403)
{
  "error": {
    "type": "provider_blocked",
    "message": "Provider 'anthropic' is not allowed for this virtual key"
  }
}