Lumnis AI
Docs
External API Keys - Python SDK

External API Keys - Python SDK

Manage BYO (Bring Your Own) API keys with the Python SDK

External API Keys (BYO Keys)

Manage your own API keys for AI providers instead of using Lumnis AI's hosted models.

Add API Key

from lumnisai import Client, ApiProvider
 
client = Client(api_key="your-api-key")
 
# Add OpenAI API key
client.add_api_key(
    provider=ApiProvider.OPENAI_API_KEY,
    api_key="sk-..."
)
 
# Add other provider keys
client.add_api_key(ApiProvider.ANTHROPIC_API_KEY, "sk-ant-...")
client.add_api_key(ApiProvider.EXA_API_KEY, "exa-...")
client.add_api_key(ApiProvider.E2B_API_KEY, "e2b-...")

Available Providers

from lumnisai import ApiProvider
 
# AI Model Providers
ApiProvider.OPENAI_API_KEY
ApiProvider.ANTHROPIC_API_KEY
ApiProvider.GOOGLE_GENAI_API_KEY
 
# Tool Providers
ApiProvider.EXA_API_KEY          # Web search
ApiProvider.E2B_API_KEY          # Code execution
ApiProvider.FIRECRAWL_API_KEY    # Web scraping
ApiProvider.TAVILY_API_KEY       # Research

List Stored Keys

# List all API keys (metadata only, not the actual keys)
keys = client.list_api_keys()
 
for key in keys:
    print(f"{key.provider}")
    print(f"  Created: {key.created_at}")
    print(f"  Key ID: {key.key_id}")

Get Specific Key

# Get key details by ID
key = client.get_api_key(key_id="key-id")
 
print(f"Provider: {key.provider}")
print(f"Created: {key.created_at}")
# Note: actual key value is never returned for security

Delete API Key

# Delete by provider name
client.delete_api_key(ApiProvider.OPENAI_API_KEY)
 
# Or by provider string
client.delete_api_key("OPENAI_API_KEY")

API Key Modes

Get Current Mode

# Check current API key mode
mode = client.get_api_key_mode()
 
print(f"Mode: {mode.api_key_mode}")
# Returns: "platform" or "byo_keys"

Set API Key Mode

from lumnisai import ApiKeyMode
 
# Use platform keys (Lumnis AI hosted)
client.set_api_key_mode(ApiKeyMode.PLATFORM)
 
# Use your own keys (BYO)
client.set_api_key_mode(ApiKeyMode.BYO_KEYS)
 
# Or use string
client.set_api_key_mode("byo_keys")

Complete Setup Example

from lumnisai import Client, ApiProvider, ApiKeyMode
import os
from dotenv import load_dotenv
 
load_dotenv()
 
# Initialize client
client = Client(api_key="your-api-key")
 
# Step 1: Check current mode
mode = client.get_api_key_mode()
print(f"Current mode: {mode.api_key_mode}")
 
# Step 2: Switch to BYO keys mode
print("\nSwitching to BYO keys mode...")
client.set_api_key_mode(ApiKeyMode.BYO_KEYS)
 
# Step 3: Add your API keys
print("Adding API keys...")
 
api_keys = [
    (ApiProvider.OPENAI_API_KEY, os.getenv("OPENAI_API_KEY")),
    (ApiProvider.ANTHROPIC_API_KEY, os.getenv("ANTHROPIC_API_KEY")),
    (ApiProvider.EXA_API_KEY, os.getenv("EXA_API_KEY")),
    (ApiProvider.E2B_API_KEY, os.getenv("E2B_API_KEY")),
]
 
for provider, key in api_keys:
    if key:
        client.add_api_key(provider, key)
        print(f"  ✓ Added {provider}")
    else:
        print(f"  ⨯ Skipped {provider} (not in environment)")
 
# Step 4: Verify keys are stored
print("\nStored API keys:")
keys = client.list_api_keys()
 
for key in keys:
    print(f"  • {key.provider} (added {key.created_at})")
 
# Step 5: Test with a request
print("\nTesting with BYO keys...")
response = client.invoke(
    "What are the latest AI trends?",
    user_id="user@example.com"
)
 
print(f"✓ Response generated using your API keys")
print(f"Output length: {len(response.output_text)} chars")

Using BYO Keys with Different Providers

OpenAI

import os
from lumnisai import Client, ApiProvider
 
client = Client(api_key="your-api-key")
 
# Add OpenAI key
client.add_api_key(
    ApiProvider.OPENAI_API_KEY,
    os.getenv("OPENAI_API_KEY")
)
 
# Set model preferences to use OpenAI
client.update_model_preferences({
    "SMART_MODEL": {
        "provider": "openai",
        "model_name": "gpt-4.1"
    }
})
 
# Now requests use your OpenAI key
response = client.invoke("Hello!")

Anthropic

# Add Anthropic key
client.add_api_key(
    ApiProvider.ANTHROPIC_API_KEY,
    os.getenv("ANTHROPIC_API_KEY")
)
 
# Use Claude models
client.update_model_preferences({
    "SMART_MODEL": {
        "provider": "anthropic",
        "model_name": "claude-3-7-sonnet-20250219"
    }
})
 
response = client.invoke("Hello!")

Multiple Providers

# Add keys for multiple providers
client.add_api_key(ApiProvider.OPENAI_API_KEY, os.getenv("OPENAI_API_KEY"))
client.add_api_key(ApiProvider.ANTHROPIC_API_KEY, os.getenv("ANTHROPIC_API_KEY"))
 
# Use different providers per request
from lumnisai import AgentConfig
 
# Use OpenAI for this request
openai_config = AgentConfig(
    coordinator_model_name="openai:gpt-4.1"
)
 
response1 = client.invoke(
    "Task 1",
    agent_config=openai_config
)
 
# Use Anthropic for this request
anthropic_config = AgentConfig(
    coordinator_model_name="anthropic:claude-3-7-sonnet-20250219"
)
 
response2 = client.invoke(
    "Task 2",
    agent_config=anthropic_config
)

Tool Provider Keys

Research and Search

# Add Exa for web search
client.add_api_key(
    ApiProvider.EXA_API_KEY,
    os.getenv("EXA_API_KEY")
)
 
# Add Tavily for research
client.add_api_key(
    ApiProvider.TAVILY_API_KEY,
    os.getenv("TAVILY_API_KEY")
)
 
# Now AI can use these tools
response = client.invoke(
    "Research the latest AI agent developments",
    user_id="user@example.com"
)

Code Execution

# Add E2B for code execution
client.add_api_key(
    ApiProvider.E2B_API_KEY,
    os.getenv("E2B_API_KEY")
)
 
# Now AI can execute code
response = client.invoke(
    "Write and run a Python script to analyze this data",
    user_id="user@example.com"
)

Async API Key Management

from lumnisai import AsyncClient, ApiProvider
import asyncio
 
async def setup_api_keys():
    client = AsyncClient(api_key="your-api-key")
    
    async with client:
        # Switch to BYO mode
        await client.set_api_key_mode("byo_keys")
        
        # Add keys concurrently
        await asyncio.gather(
            client.add_api_key(ApiProvider.OPENAI_API_KEY, os.getenv("OPENAI_API_KEY")),
            client.add_api_key(ApiProvider.ANTHROPIC_API_KEY, os.getenv("ANTHROPIC_API_KEY")),
            client.add_api_key(ApiProvider.EXA_API_KEY, os.getenv("EXA_API_KEY"))
        )
        
        # List all keys
        keys = await client.list_api_keys()
        print(f"Added {len(keys)} API keys")
 
asyncio.run(setup_api_keys())

Best Practices

Use Environment Variables

import os
from dotenv import load_dotenv
 
# Load from .env file
load_dotenv()
 
# Never hardcode keys
client.add_api_key(
    ApiProvider.OPENAI_API_KEY,
    os.getenv("OPENAI_API_KEY")  # From environment
)

Check Before Adding

def add_key_if_not_exists(client, provider, key_value):
    """Add key only if not already stored."""
    existing = client.list_api_keys()
    
    if any(k.provider == provider for k in existing):
        print(f"{provider} already configured")
        return False
    
    client.add_api_key(provider, key_value)
    print(f"Added {provider}")
    return True
 
# Usage
add_key_if_not_exists(
    client,
    ApiProvider.OPENAI_API_KEY,
    os.getenv("OPENAI_API_KEY")
)

Update Keys Periodically

def refresh_api_key(client, provider, new_key):
    """Replace existing key with new one."""
    try:
        # Delete old key
        client.delete_api_key(provider)
    except:
        pass  # Key might not exist
    
    # Add new key
    client.add_api_key(provider, new_key)
    print(f"Refreshed {provider}")
 
# Usage
refresh_api_key(
    client,
    ApiProvider.OPENAI_API_KEY,
    os.getenv("NEW_OPENAI_KEY")
)

Validate Keys After Adding

def add_and_test_key(client, provider, key_value):
    """Add key and verify it works."""
    # Add key
    client.add_api_key(provider, key_value)
    
    # Test with simple request
    try:
        response = client.invoke(
            "Test",
            user_id="test@example.com"
        )
        print(f"✓ {provider} key is valid")
        return True
    except Exception as e:
        print(f"✗ {provider} key test failed: {e}")
        # Clean up invalid key
        client.delete_api_key(provider)
        return False

Platform vs BYO Keys

Platform Mode (Default)

# Use Lumnis AI's hosted models
client.set_api_key_mode("platform")
 
# Simple to use, no API keys needed
response = client.invoke("Hello!")
 
# Billing through Lumnis AI

BYO Keys Mode

# Use your own API keys
client.set_api_key_mode("byo_keys")
 
# Add your keys
client.add_api_key(ApiProvider.OPENAI_API_KEY, "sk-...")
 
# Full control over model providers
response = client.invoke("Hello!")
 
# Direct billing from providers

When to Use Each

Use Platform Mode when:

  • You want simplicity and convenience
  • You're prototyping or getting started
  • You want unified billing
  • You don't have provider API keys

Use BYO Keys Mode when:

  • You have existing provider relationships
  • You want cost optimization
  • You need specific provider features
  • You require direct provider billing

Migration Example

From Platform to BYO

from lumnisai import Client, ApiProvider, ApiKeyMode
 
client = Client(api_key="your-api-key")
 
# Currently using platform mode
print("Current mode:", client.get_api_key_mode().api_key_mode)
 
# Switch to BYO
print("Switching to BYO keys mode...")
client.set_api_key_mode(ApiKeyMode.BYO_KEYS)
 
# Add your keys
client.add_api_key(ApiProvider.OPENAI_API_KEY, os.getenv("OPENAI_API_KEY"))
client.add_api_key(ApiProvider.ANTHROPIC_API_KEY, os.getenv("ANTHROPIC_API_KEY"))
 
# Configure model preferences
client.update_model_preferences({
    "SMART_MODEL": {
        "provider": "openai",
        "model_name": "gpt-4.1"
    }
})
 
print("Migration complete!")
 
# Test
response = client.invoke("Test message")
print("✓ Working with BYO keys")

From BYO to Platform

# Switch back to platform mode
client.set_api_key_mode(ApiKeyMode.PLATFORM)
 
# Optionally remove your keys
for key in client.list_api_keys():
    client.delete_api_key(key.provider)
 
print("Switched to platform mode")
Model PreferencesAdvanced Usage