Virtual Keys Guide

Secure API keys with built-in governance Virtual keys provide authentication, budget controls, and rate limiting.

Overview

Virtual Keys are the primary authentication mechanism for Korad.AI. Each key includes:

• Hash-based authentication (SHA-256)
• Budget limits (monthly/weekly/daily/hourly)
• Rate limits (requests and tokens per period)
• Provider configuration (allowed models and weights)

Key Format

sk-bf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

• sk-bf-: Prefix indicating Korad.AI Bifrost key
• xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx: UUID identifier

Creating Virtual Keys

via API

curl -X POST http://localhost:8081/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "budget_limit_cents": 5000,
    "budget_reset_duration": "1M",
    "rate_limit_requests": 1000,
    "rate_limit_reset_duration": "1h"
  }'

via Configuration

Add to config.dev.json:

{
  "governance": {
    "virtual_keys": [
      {
        "id": "prod-key-1",
        "name": "Production Key",
        "description": "Production usage with $50/month budget",
        "value": "sk-bf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "is_active": true,
        "budget_id": "prod-monthly-budget",
        "rate_limit_id": "prod-rate-limit"
      }
    ]
  }
}

Key Configuration

Budget Limits

Control spending with budget caps:

{
  "budgets": [
    {
      "id": "monthly-budget",
      "name": "Monthly Budget",
      "max_limit": 50.0,
      "reset_duration": "1M"
    }
  ]
}

Reset durations:

• 1M - Monthly
• 1w - Weekly
• 1d - Daily
• 1h - Hourly

Rate Limits

Prevent abuse with rate limits:

{
  "rate_limits": [
    {
      "id": "rate-limit",
      "name": "Rate Limit",
      "request_max_limit": 1000,
      "request_reset_duration": "1h",
      "token_max_limit": 1000000,
      "token_reset_duration": "1h"
    }
  ]
}

Provider Configuration

Restrict which models a key can use:

{
  "provider_configs": [
    {
      "provider": "anthropic",
      "weight": 1.0,
      "allowed_models": [
        "claude-haiku-4-5-20251001",
        "claude-sonnet-4-5-20250929"
      ]
    }
  ]
}

Using Virtual Keys

In Requests

curl -X POST http://localhost:8084/v1/chat/completions \
  -H "x-bf-vk: sk-bf-YOUR_VIRTUAL_KEY" \
  -d '{...}'

In Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8084/v1",
    api_key="sk-bf-YOUR_VIRTUAL_KEY"
)

In JavaScript

const openai = new OpenAI({
  baseURL: 'http://localhost:8084/v1',
  apiKey: 'sk-bf-YOUR_VIRTUAL_KEY',
});

Managing Keys

List Keys

curl http://localhost:8081/api/governance/virtual-keys

Response:

{
  "keys": [
    {
      "id": "key-1",
      "name": "Production Key",
      "key_prefix": "sk-bf-a1b2c3d4",
      "is_active": true,
      "current_usage_cents": 2500,
      "budget_limit_cents": 5000
    }
  ]
}

Update Key

curl -X PUT http://localhost:8081/api/governance/virtual-keys/key-1 \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Delete Key

curl -X DELETE http://localhost:8081/api/governance/virtual-keys/key-1

Best Practices

1. Use Separate Keys for Environments

Development:  sk-bf-dev-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Staging:      sk-bf-staging-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Production:   sk-bf-prod-xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Set Appropriate Budgets

Environment	Budget	Reset
Development	$10	Monthly
Staging	$50	Monthly
Production	$500+	Monthly

3. Implement Key Rotation

Rotate keys regularly:

1. Create new key
2. Update application with new key
3. Verify new key works
4. Disable old key
5. Delete old key after 30 days

4. Monitor Usage

Track key usage in real-time:

curl http://localhost:8081/api/governance/virtual-keys/key-1/usage

Security

Key Storage

• ✅ Store in environment variables
• ✅ Use secret management (AWS Secrets Manager, etc.)
• ❌ Never commit to git
• ❌ Never hardcode in application

Key Permissions

Restrict key capabilities:

{
  "allowed_models": ["claude-haiku-4-5-20251001"],
  "max_tokens": 10000,
  "disable_tools": true
}

Audit Logging

All key usage is logged:

{
  "timestamp": "2025-02-08T10:30:00Z",
  "key_id": "key-1",
  "model": "claude-sonnet-4-5-20250929",
  "tokens_used": 1500,
  "cost_cents": 5
}

Troubleshooting

Key Not Working

# Verify key exists
curl http://localhost:8081/api/governance/virtual-keys

# Check key is active
curl http://localhost:8081/api/governance/virtual-keys/key-1

Budget Exceeded

{
  "error": {
    "message": "Budget exceeded: $50.00 limit reached",
    "type": "budget_exceeded_error"
  }
}

Solution: Wait for reset or increase budget limit.

Rate Limit Exceeded

{
  "error": {
    "message": "Rate limit exceeded: 1000 requests/hour",
    "type": "rate_limit_error"
  }
}

Solution: Implement exponential backoff or increase rate limit.

---

Secure your API access with virtual keys.