Use Case

BYOK (Bring Your Own Keys)

Use your own API keys from OpenAI, Anthropic, and other providers while leveraging ParrotRouter's advanced features

What is BYOK?

Bring Your Own Keys (BYOK) allows you to use your existing API keys from various AI providers while benefiting from ParrotRouter's unified API, advanced routing, monitoring, and management features. This gives you direct billing relationships with providers while leveraging our infrastructure.

Direct Billing

Pay providers directly at their standard rates

Enhanced Security

Keys encrypted and never logged or stored

Team Management

Share provider access without sharing keys

Setting Up BYOK

Configure your provider API keys through the API or dashboard:

Configure Provider Keyspython

import requests

# Add your provider API keys
response = requests.post(
    "https://api.parrotrouter.com/v1/providers/keys",
    headers={
        "Authorization": "Bearer your-parrotrouter-key",
        "Content-Type": "application/json"
    },
    json={
        "providers": [
            {
                "name": "openai",
                "api_key": "sk-your-openai-api-key",
                "organization_id": "org-your-org-id",  # Optional
                "settings": {
                    "default_model": "gpt-4-turbo-preview",
                    "max_tokens_default": 4000,
                    "temperature_default": 0.7
                }
            },
            {
                "name": "anthropic",
                "api_key": "sk-ant-your-anthropic-key",
                "settings": {
                    "default_model": "claude-3-opus-20240229",
                    "max_tokens_default": 4000
                }
            },
            {
                "name": "google",
                "api_key": "your-google-api-key",
                "settings": {
                    "default_model": "gemini-pro",
                    "safety_settings": "medium"
                }
            },
            {
                "name": "cohere",
                "api_key": "your-cohere-api-key"
            },
            {
                "name": "perplexity",
                "api_key": "pplx-your-perplexity-key"
            }
        ],
        "encryption": {
            "method": "AES-256-GCM",
            "key_rotation": True,
            "rotation_days": 90
        }
    }
)

print(f"BYOK configured: {response.json()}")

# List configured providers
providers = requests.get(
    "https://api.parrotrouter.com/v1/providers",
    headers={"Authorization": "Bearer your-parrotrouter-key"}
).json()

print("
Configured providers:")
for provider in providers['providers']:
    print(f"  - {provider['name']}: {provider['status']}")
    print(f"    Models available: {', '.join(provider['available_models'])}")

Your API keys are encrypted at rest and in transit. ParrotRouter never logs or stores your actual keys in plaintext.

Using BYOK with Requests

Once configured, use your keys by specifying the provider in your requests:

Direct Provider Routing

# Force specific provider with BYOK
response = requests.post(
    "https://api.parrotrouter.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer your-parrotrouter-key",
        "X-Use-BYOK": "true",  # Enable BYOK mode
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-4-turbo-preview",
        "provider": "openai",  # Force OpenAI provider
        "messages": [
            {"role": "user", "content": "Hello!"}
        ],
        "routing": {
            "strategy": "direct",  # No fallbacks
            "use_byok_only": True  # Only use your keys
        }
    }
)

# Or use automatic provider selection
response = requests.post(
    "https://api.parrotrouter.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer your-parrotrouter-key",
        "X-Use-BYOK": "true"
    },
    json={
        "model": "claude-3-opus-20240229",  # Auto-selects Anthropic
        "messages": [
            {"role": "user", "content": "Hello!"}
        ],
        "routing": {
            "strategy": "byok_preferred",  # Prefer BYOK, fallback if needed
            "fallback_to_parrotrouter": True
        }
    }
)

Multi-Provider Fallbacks

# Configure fallback chain with BYOK
response = requests.post(
    "https://api.parrotrouter.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer your-parrotrouter-key",
        "X-Use-BYOK": "true"
    },
    json={
        "model": "gpt-4",  # Request GPT-4 class model
        "messages": [
            {"role": "user", "content": "Analyze this data..."}
        ],
        "routing": {
            "strategy": "fallback_chain",
            "provider_order": [
                "openai",      # Try your OpenAI key first
                "anthropic",   # Then your Anthropic key
                "google",      # Then your Google key
                "parrotrouter" # Finally, ParrotRouter's keys
            ],
            "fallback_reasons": [
                "rate_limit",
                "timeout",
                "server_error",
                "model_not_available"
            ]
        }
    }
)

# Check which provider was used
print(f"Provider used: {response.headers.get('X-Provider-Used')}")
print(f"BYOK used: {response.headers.get('X-BYOK-Used')}")

Team Key Management

Share provider access with your team without exposing API keys:

Team BYOK Configurationpython

# Create team with BYOK access
team_config = {
    "name": "Engineering Team",
    "byok_permissions": {
        "providers": {
            "openai": {
                "enabled": True,
                "models": ["gpt-4-turbo-preview", "gpt-3.5-turbo"],
                "max_cost_per_day": 100.00,
                "require_approval_above": 10.00
            },
            "anthropic": {
                "enabled": True,
                "models": ["claude-3-sonnet-20240229"],  # Limit to Sonnet
                "max_cost_per_day": 50.00
            },
            "google": {
                "enabled": False  # No access to Google
            }
        },
        "usage_controls": {
            "log_all_requests": True,
            "require_project_tag": True,
            "allowed_projects": ["project-a", "project-b"],
            "block_sensitive_content": True
        }
    },
    "members": [
        {
            "email": "developer@company.com",
            "role": "developer",
            "byok_access": True
        },
        {
            "email": "intern@company.com",
            "role": "viewer",
            "byok_access": False  # Can view but not use BYOK
        }
    ]
}

response = requests.post(
    "https://api.parrotrouter.com/v1/teams",
    headers={"Authorization": "Bearer your-admin-key"},
    json=team_config
)

# Team member uses BYOK without seeing keys
team_response = requests.post(
    "https://api.parrotrouter.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer team-member-key",
        "X-Team-ID": "team_123",
        "X-Project-Tag": "project-a"  # Required by policy
    },
    json={
        "model": "gpt-4-turbo-preview",
        "messages": [{"role": "user", "content": "Hello!"}]
        # Automatically uses team's BYOK configuration
    }
)

Cost Tracking & Analytics

Real-time Cost Monitoring

# Get BYOK usage analytics
analytics = requests.get(
    "https://api.parrotrouter.com/v1/analytics/byok",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    params={
        "period": "current_month",
        "group_by": "provider,model,team"
    }
).json()

print("BYOK Usage Summary:")
print(f"Total BYOK requests: {analytics['total_requests']}")
print(f"Estimated costs: $" + str(analytics['estimated_costs']))

print("
By Provider:")
for provider in analytics['by_provider']:
    print(f"
{provider['name']}:")
    print(f"  Requests: {provider['requests']}")
    print(f"  Estimated cost: $" + str(provider['estimated_cost']))
    print(f"  Average latency: {provider['avg_latency_ms']}ms")
    print(f"  Models used: {', '.join(provider['models_used'])}")

# Set up cost alerts
alert_config = {
    "alerts": [
        {
            "type": "byok_cost_threshold",
            "provider": "openai",
            "threshold": 100.00,
            "period": "daily",
            "notify": ["alerts@company.com"]
        },
        {
            "type": "byok_usage_anomaly",
            "sensitivity": "high",
            "notify": ["security@company.com"]
        }
    ]
}

requests.post(
    "https://api.parrotrouter.com/v1/alerts",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    json=alert_config
)

Cost Comparison

# Compare BYOK vs ParrotRouter costs
comparison = requests.get(
    "https://api.parrotrouter.com/v1/analytics/cost-comparison",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    params={"period": "last_30_days"}
).json()

print("Cost Comparison (Last 30 Days):")
print(f"
Using BYOK:")
print(f"  Provider charges: $" + str(comparison['byok']['provider_costs']))
print(f"  ParrotRouter fees: $" + str(comparison['byok']['platform_fees']))
print(f"  Total: $" + str(comparison['byok']['total']))

print(f"
Using ParrotRouter keys:")
print(f"  Total charges: $" + str(comparison['parrotrouter']['total']))

print(f"
Savings with BYOK: $" + str(comparison['savings']))
print(f"Savings percentage: {comparison['savings_percentage']}%")

# Export detailed billing report
export = requests.post(
    "https://api.parrotrouter.com/v1/billing/export",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    json={
        "type": "byok_usage",
        "period": "last_quarter",
        "format": "csv",
        "include": [
            "provider_breakdown",
            "model_breakdown", 
            "team_breakdown",
            "hourly_usage"
        ]
    }
)

Advanced BYOK Features

Provider Health Monitoring

# Monitor provider health
health = requests.get(
    "https://api.parrotrouter.com/v1/providers/health",
    headers={"Authorization": "Bearer your-parrotrouter-key"}
).json()

for provider in health['providers']:
    print(f"
{provider['name']}:")
    print(f"  Status: {provider['status']}")
    print(f"  Latency: {provider['latency_ms']}ms")
    print(f"  Success rate: {provider['success_rate']}%")
    print(f"  Rate limit remaining: {provider['rate_limit_remaining']}")
    
    if provider['issues']:
        print(f"  Issues: {', '.join(provider['issues'])}")

# Auto-disable unhealthy providers
requests.post(
    "https://api.parrotrouter.com/v1/providers/health-check",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    json={
        "auto_disable": True,
        "health_threshold": 95,  # 95% success rate
        "latency_threshold": 1000,  # 1 second
        "check_interval": 60  # Check every minute
    }
)

Key Rotation

# Rotate provider API keys
rotation = requests.post(
    "https://api.parrotrouter.com/v1/providers/keys/rotate",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    json={
        "provider": "openai",
        "new_api_key": "sk-new-openai-api-key",
        "rotation_strategy": "gradual",  # or "immediate"
        "grace_period_minutes": 30,  # Keep old key active
        "test_before_switch": True,  # Verify new key works
        "notification_webhooks": [
            "https://api.company.com/key-rotated"
        ]
    }
)

print(f"Rotation status: {rotation.json()['status']}")
print(f"Old key expires: {rotation.json()['old_key_expires_at']}")

# Schedule automatic rotation
schedule = requests.post(
    "https://api.parrotrouter.com/v1/providers/keys/rotation-schedule",
    headers={"Authorization": "Bearer your-parrotrouter-key"},
    json={
        "provider": "anthropic",
        "schedule": "0 0 1 * *",  # Monthly
        "notification_email": "security@company.com"
    }
)

Security Best Practices

1.
Use Environment-Specific Keys
Never use production provider keys in development
2.
Enable IP Restrictions
Limit BYOK usage to known IP addresses
3.
Regular Key Rotation
Rotate provider keys at least quarterly
4.
Monitor Usage Patterns
Set up alerts for unusual BYOK usage
5.
Use Team Permissions
Grant minimum necessary access to team members

Never commit API keys to version control or share them in plain text. Always use secure key management systems.

Common Use Cases

Enterprise Compliance

Meet compliance requirements by maintaining direct relationships with AI providers while using ParrotRouter for management.

# Compliance-focused configuration
{
    "byok_compliance": {
        "data_residency": "never_store_keys",
        "audit_logging": "all_requests",
        "encryption": "FIPS-140-2",
        "key_access_logs": True
    }
}

Cost Optimization

Use your enterprise agreements and volume discounts while benefiting from intelligent routing.

# Cost-optimized routing
{
    "routing": {
        "strategy": "cost_optimized",
        "prefer_byok": True,
        "cost_weights": {
            "openai": 0.8,  # Enterprise discount
            "anthropic": 1.0
        }
    }
}