Virtual Keys

Virtual keys are a way to manage access to your AI models.

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)

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

You can also use Authorization, x-api-key and x-goog-api-key headers to pass direct keys to the provider. Read more about it in Direct Key Bypass.

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

1. Go to Virtual Keys

2. Click on Add Virtual Key button

   

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)

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

1. Go to Users & Groups → Teams

2. Click on Add Team button

   

Fill the form and click on Create Team button

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

1. Go to Users & Groups → Customers

2. Click on Add Customer button

   

Fill the form and click on Create Customer button

3. Assign Teams to Customer

   • Go to Teams page
   • Edit the team and assign it to the customer
   • Click on Save button

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

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

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"
  }
}