Multi-Tenancy Guide

TL;DR: Igris Overture provides complete tenant isolation with BYOK (Bring Your Own Key), per-tenant budgets, and usage tracking. Perfect for SaaS platforms serving multiple customers.

What You Get

Multi-tenancy in Igris Overture ensures:

Complete Isolation: Tenant data never mixes - each tenant has their own space
BYOK Support: Each tenant brings their own provider API keys (OpenAI, Anthropic, etc.)
Per-Tenant Budgets: Set spending limits and get alerts before hitting them
Custom Configuration: Different routing policies and features per tenant
Usage Tracking: Detailed cost and performance metrics per tenant

Quick Start

Step 1: Create a Tenant

POST /v1/admin/tenants
Content-Type: application/json

{
  "name": "Acme Corp",
  "tier": "growth",
  "email": "admin@acme.com",
  "monthly_budget_usd": 5000.00
}

Response:

{
  "tenant_id": "tenant_abc123",
  "name": "Acme Corp",
  "tier": "growth",
  "api_keys": [
    {
      "key": "sk-abc123xyz789...",  // Save this - only shown once
      "key_preview": "sk-...xyz789"
    }
  ],
  "features": {
    "thompson_sampling": true,
    "speculative_execution": true,
    "council_mode": true
  }
}

Step 2: Add Provider Keys (BYOK)

Each tenant brings their own provider API keys:

POST /v1/tenants/{tenant_id}/providers/openai/keys
Content-Type: application/json

{
  "api_key": "sk-openai-key-here",
  "config": {
    "timeout": 30,
    "max_retries": 3
  }
}

Add multiple providers:

# Add Anthropic
POST /v1/tenants/{tenant_id}/providers/anthropic/keys
{"api_key": "sk-ant-..."}

# Add Google Gemini
POST /v1/tenants/{tenant_id}/providers/google/keys
{"api_key": "AIza..."}

Step 3: Make Requests

Use the tenant's API key to make requests:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.igrisinertial.com/v1",
    api_key="sk-abc123xyz789..."  # Tenant's API key
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Automatically uses tenant's provider keys
# Costs tracked per tenant

BYOK (Bring Your Own Key)

Why BYOK?

Security: Tenant API keys never leave your infrastructure
Cost Control: Tenants pay their own provider bills
Compliance: Meet data residency and security requirements
Flexibility: Each tenant can use different providers

Managing Provider Keys

List tenant's providers:

GET /v1/tenants/{tenant_id}/providers

Response:

{
  "providers": [
    {
      "provider_id": "openai",
      "models": ["gpt-4", "gpt-3.5-turbo"],
      "status": "active",
      "last_health_check": "2025-11-30T12:00:00Z"
    },
    {
      "provider_id": "anthropic",
      "models": ["claude-3-sonnet", "claude-3-opus"],
      "status": "active"
    }
  ]
}

Remove a provider:

DELETE /v1/tenants/{tenant_id}/providers/openai

Tier-Based Features

Different tiers unlock different features:

Feature	Trial	Developer	Growth	Scale
Requests/Month	50k	500k	2M	Unlimited
Requests/Second	10	10	50	1000
Providers	3	5	10	20
API Keys	1	3	10	Unlimited
Thompson Sampling	✓	✓	✓	✓
Speculative Execution	-	-	✓	✓
Council Mode	-	-	-	✓
Budget Enforcement	-	✓	✓	✓
SLA	-	-	-	99.9%
Audit Logs	-	-	✓	✓

Usage Tracking

Get Tenant Usage

GET /v1/tenants/{tenant_id}/usage?period=month

Response:

{
  "tenant_id": "tenant_abc123",
  "period": "month",
  "requests": {
    "total": 1456789,
    "successful": 1453211,
    "failed": 3578,
    "success_rate": 0.998,
    "by_provider": {
      "openai": 892345,
      "anthropic": 564444
    }
  },
  "cost": {
    "total_usd": 2345.67,
    "by_provider": {
      "openai": 1234.56,
      "anthropic": 1111.11
    },
    "budget_used_percent": 46.91
  },
  "latency": {
    "avg_ms": 287,
    "p95_ms": 456,
    "p99_ms": 678
  }
}

Cost Breakdown

GET /v1/tenants/{tenant_id}/costs/breakdown

Response:

{
  "total_cost_usd": 2345.67,
  "breakdown": {
    "by_provider": {
      "openai": {
        "requests": 892345,
        "cost_usd": 1234.56,
        "avg_cost_per_request": 0.00138
      },
      "anthropic": {
        "requests": 564444,
        "cost_usd": 1111.11,
        "avg_cost_per_request": 0.00197
      }
    },
    "by_routing_policy": {
      "thompson-sampling": 1456.78,
      "speculative-execution": 678.90,
      "council-mode": 209.99
    }
  },
  "projections": {
    "end_of_month_usd": 2891.45,
    "trend": "increasing"
  }
}

Budget Management

Set Monthly Budget

POST /v1/tenants/{tenant_id}/budget
Content-Type: application/json

{
  "monthly_budget_usd": 5000.00,
  "alert_threshold": 0.90,
  "hard_cap": true,
  "notification_channels": ["email", "webhook"],
  "webhook_url": "https://example.com/webhook"
}

Budget Alerts

You'll receive alerts when spending approaches limits:

At 90% of budget:

Subject: Budget Alert - 90% of Monthly Limit Reached

Your Igris Overture account has used 90% of your monthly budget:

Budget: $5,000.00
Used: $4,500.00
Remaining: $500.00

At 100% of budget (with hard cap):

Requests are blocked with HTTP 402:

{
  "error": {
    "type": "budget_limit_error",
    "code": "monthly_budget_exceeded",
    "message": "Monthly budget limit of $5,000.00 has been exceeded",
    "current_usage_usd": 5123.45,
    "budget_limit_usd": 5000.00
  }
}

API Key Management

Create API Key

Create multiple API keys per tenant (for different environments, teams, etc.):

POST /v1/tenants/{tenant_id}/api-keys
Content-Type: application/json

{
  "name": "Production Key",
  "expires_in_days": 365
}

Response:

{
  "key_id": "key_xyz789",
  "key": "sk-abc123xyz789...",  // Only shown once - save it!
  "key_preview": "sk-...xyz789",
  "name": "Production Key",
  "expires_at": "2026-11-30T12:00:00Z"
}

List API Keys

GET /v1/tenants/{tenant_id}/api-keys

Response:

{
  "api_keys": [
    {
      "key_id": "key_xyz789",
      "key_preview": "sk-...xyz789",
      "name": "Production Key",
      "created_at": "2025-11-30T12:00:00Z",
      "last_used_at": "2025-12-01T08:30:00Z",
      "expires_at": "2026-11-30T12:00:00Z"
    }
  ]
}

Revoke API Key

DELETE /v1/tenants/{tenant_id}/api-keys/{key_id}

Tenant Management

Update Tenant Tier

Upgrade or downgrade a tenant's tier:

PATCH /v1/admin/tenants/{tenant_id}/tier
Content-Type: application/json

{
  "tier": "scale",
  "grace_period_days": 30
}

Response:

{
  "tenant_id": "tenant_abc123",
  "tier": "scale",
  "old_tier": "growth",
  "new_limits": {
    "max_requests_per_month": -1,
    "max_requests_per_second": 1000
  },
  "new_features": {
    "on_premise_deployment": true,
    "sla": "99.9%"
  }
}

Suspend Tenant

Temporarily disable a tenant (e.g., for non-payment):

POST /v1/admin/tenants/{tenant_id}/suspend
Content-Type: application/json

{
  "reason": "Payment failure",
  "notify": true
}

Suspended tenants receive HTTP 403 on all requests.

Resume Tenant

Reactivate a suspended tenant:

POST /v1/admin/tenants/{tenant_id}/resume

Complete Isolation

Every aspect of Igris Overture enforces tenant isolation:

API Keys: Each tenant has unique API keys
Provider Keys: Tenant provider keys are encrypted and isolated
Requests: All requests are scoped to tenant
Data: Usage data, metrics, and logs are separated
Budgets: Independent budget tracking per tenant
Rate Limits: Per-tenant rate limiting

Best Practices

Security

Rotate API keys regularly (recommended: every 90 days)
Set expiration dates on API keys
Use different keys for dev/staging/production
Monitor key usage for anomalies in the dashboard

Cost Control

Set budget alerts at 80% and 90%
Review usage weekly for trends
Enable hard caps to prevent overages
Monitor speculative execution waste (should be <30%)

Performance

Use appropriate tiers based on request volume
Monitor latency metrics per tenant
Review provider performance to optimize routing

Next Steps

Provider Keys - Configure BYOK providers
Pricing Tiers - Compare tier features
API Reference - Complete API documentation
Observability - Monitor tenant usage