Overview

Visca AI Gateway provides enterprise-grade API key management with granular access control, usage limits, and comprehensive audit logging.

Fine-Grained Access

Control which models, providers, and features each key can access

Usage Limits

Set spending caps, rate limits, and quota restrictions

Audit Logs

Track every request with complete audit trails

IAM Rules

Implement complex access policies with IAM-style rules

Creating API Keys

Navigate to API Keys

Go to your dashboard and click Create API Key

Configure basic settings

Name: Descriptive name (e.g., “Production App”, “Development”, “User Analytics”) - Description: Optional notes about the key’s purpose - Expiration: Set expiry date or never expire

Set permissions

Choose access level: - Full Access: All models and features - Read Only: Only list models and view usage - Custom: Fine-grained control (recommended)

Configure limits

Set usage restrictions: - Rate Limit: Requests per minute/hour/day - Budget: Maximum spending per day/month - Quota: Total requests allowed

Save and copy

Copy your API key immediately—it won’t be shown again!

IAM-Style Access Control

Define precise access policies using IAM-style rules:

Allow Specific Models

{
	"version": "2024-01-01",
	"statements": [
		{
			"effect": "Allow",
			"actions": ["chat:completions", "chat:stream"],
			"resources": [
				"model:gpt-4o",
				"model:gpt-4o-mini",
				"model:claude-3-5-sonnet-20241022"
			]
		}
	]
}

Restrict by Provider

{
	"version": "2024-01-01",
	"statements": [
		{
			"effect": "Allow",
			"actions": ["*"],
			"resources": ["provider:openai", "provider:anthropic"]
		},
		{
			"effect": "Deny",
			"actions": ["*"],
			"resources": ["provider:*"],
			"condition": {
				"not_in": ["openai", "anthropic"]
			}
		}
	]
}

Time-Based Access

{
	"version": "2024-01-01",
	"statements": [
		{
			"effect": "Allow",
			"actions": ["*"],
			"resources": ["*"],
			"condition": {
				"time_between": {
					"start": "09:00",
					"end": "17:00",
					"timezone": "America/New_York"
				}
			}
		}
	]
}

Budget-Based Restrictions

{
	"version": "2024-01-01",
	"statements": [
		{
			"effect": "Allow",
			"actions": ["chat:completions"],
			"resources": ["model:gpt-4o"],
			"condition": {
				"monthly_budget_under": 1000.0
			}
		},
		{
			"effect": "Allow",
			"actions": ["chat:completions"],
			"resources": ["model:gpt-3.5-turbo"],
			"condition": {
				"monthly_budget_over": 1000.0
			}
		}
	]
}

Usage Limits

Rate Limiting

Control request frequency:

Per Minute
Per Hour
Per Day

{
  "rate_limits": {
    "per_minute": 60,
    "burst": 10
  }
}

{
  "rate_limits": {
    "per_hour": 1000,
    "per_minute": 60
  }
}

{
  "rate_limits": {
    "per_day": 10000,
    "per_hour": 500,
    "per_minute": 20
  }
}

Spending Limits

Set budget caps:

{
	"budget_limits": {
		"daily": 100.0,
		"monthly": 2000.0,
		"total": 10000.0,
		"currency": "USD"
	},
	"budget_alerts": {
		"thresholds": [50, 75, 90],
		"notify_email": "admin@company.com"
	}
}

Token Quotas

Limit token usage:

{
	"token_limits": {
		"daily": 1000000,
		"monthly": 25000000,
		"per_request_max": 100000
	}
}

Security Best Practices

Key Rotation

Rotate API keys regularly:

Create new key

Generate a new API key with same permissions

Update applications

Deploy new key to all applications

Monitor usage

Verify new key is working correctly

Revoke old key

Delete the old key after confirming migration

Recommended rotation schedule: Every 90 days

Environment Isolation

Use separate keys for each environment: ```bash # Development VISCA_API_KEY_DEV=vsk_dev_… # Staging VISCA_API_KEY_STAGING=vsk_staging_…

Production VISCA_API_KEY_PROD=vsk_prod_… ``` Configure different limits

for each: - Dev: Unlimited, all models - Staging: Production-like limits - Production: Strict limits, monitoring

Secret Storage

Never commit keys to version control! Use secure storage: - AWS Secrets Manager - Azure Key Vault - HashiCorp Vault - Google Secret Manager - Environment variables (with encryption) python # Good ✅ api_key = os.environ.get("VISCA_API_KEY") # Bad ❌ api_key = "vsk_1234567890abcdef"

Monitoring & Alerts

Set up alerts for:

Budget thresholds reached
Unusual usage patterns
Rate limit exceeded
Failed authentication attempts
Key compromises detected

{
  "alerts": {
    "budget_threshold": [50, 75, 90],
    "rate_limit_percentage": 80,
    "failed_auth_threshold": 10,
    "unusual_patterns": true
  }
}

Audit Logging

Track all API key usage with comprehensive logs:

View Audit Logs

curl https://api.visca.ai/v1/audit-logs \
  -H "Authorization: Bearer $VISCA_API_KEY" \
  -H "X-API-Key-ID: key_abc123"

Log Contents

Each log entry includes:

{
	"timestamp": "2024-12-03T10:30:00Z",
	"api_key_id": "key_abc123",
	"api_key_name": "Production App",
	"request_id": "req_xyz789",
	"action": "chat.completions.create",
	"model": "gpt-4o",
	"provider": "openai",
	"status": "success",
	"latency_ms": 245,
	"tokens": {
		"prompt": 150,
		"completion": 200,
		"total": 350
	},
	"cost_usd": 0.00525,
	"metadata": {
		"user_id": "user_123",
		"app_name": "customer_support"
	},
	"ip_address": "203.0.113.42",
	"user_agent": "openai-python/1.3.0"
}

Multi-Tenant API Keys

Create hierarchical key structures for organizations:

Organization-Level Keys

{
	"key_type": "organization",
	"organization_id": "org_abc123",
	"permissions": {
		"manage_keys": true,
		"view_all_usage": true,
		"manage_billing": true
	}
}

Team-Level Keys

{
	"key_type": "team",
	"organization_id": "org_abc123",
	"team_id": "team_xyz789",
	"permissions": {
		"models": ["gpt-4o", "claude-3-5-sonnet-20241022"],
		"monthly_budget": 5000.0
	}
}

User-Level Keys

{
	"key_type": "user",
	"organization_id": "org_abc123",
	"team_id": "team_xyz789",
	"user_id": "user_123",
	"permissions": {
		"models": ["gpt-3.5-turbo"],
		"daily_budget": 50.0,
		"rate_limit_per_minute": 20
	}
}

Temporary Keys

Generate short-lived keys for specific use cases:

import requests

response = requests.post(
    "https://api.visca.ai/v1/api-keys/temporary",
    headers={"Authorization": f"Bearer {master_key}"},
    json={
        "expires_in": 3600,  # 1 hour
        "permissions": {
            "models": ["gpt-4o"],
            "max_requests": 100
        },
        "metadata": {
            "purpose": "demo_session",
            "user_id": "demo_user_123"
        }
    }
)

temp_key = response.json()["api_key"]

IP Allowlisting

Restrict key usage to specific IP addresses:

{
	"ip_allowlist": {
		"enabled": true,
		"addresses": ["203.0.113.0/24", "198.51.100.42"]
	}
}

Webhooks for Key Events

Receive notifications about key activities:

{
	"webhooks": {
		"enabled": true,
		"url": "https://yourapp.com/webhooks/visca",
		"events": [
			"key.created",
			"key.revoked",
			"key.limit_exceeded",
			"key.budget_threshold",
			"key.suspicious_activity"
		],
		"secret": "whsec_..."
	}
}

Managing Keys Programmatically

Create API Key

import requests

response = requests.post(
    "https://api.visca.ai/v1/api-keys",
    headers={"Authorization": f"Bearer {admin_key}"},
    json={
        "name": "New Application Key",
        "description": "Key for mobile app",
        "permissions": {
            "models": ["gpt-4o-mini", "claude-3-haiku"],
            "actions": ["chat:completions"]
        },
        "rate_limits": {
            "per_minute": 100
        },
        "budget_limits": {
            "monthly": 1000.00
        },
        "expires_at": "2025-12-31T23:59:59Z"
    }
)

new_key = response.json()
print(f"Created key: {new_key['api_key']}")

List All Keys

response = requests.get(
    "https://api.visca.ai/v1/api-keys",
    headers={"Authorization": f"Bearer {admin_key}"}
)

keys = response.json()["keys"]
for key in keys:
    print(f"{key['name']}: {key['status']}")

Revoke API Key

requests.delete(
    f"https://api.visca.ai/v1/api-keys/{key_id}",
    headers={"Authorization": f"Bearer {admin_key}"}
)

Update Key Permissions

requests.patch(
    f"https://api.visca.ai/v1/api-keys/{key_id}",
    headers={"Authorization": f"Bearer {admin_key}"},
    json={
        "rate_limits": {
            "per_minute": 200  # Increase limit
        },
        "budget_limits": {
            "monthly": 2000.00  # Increase budget
        }
    }
)

Troubleshooting

401 Unauthorized

Causes:

Invalid API key
Expired key
Revoked key

Solution:

Verify key is correct
Check expiration date
Generate new key if needed

403 Forbidden

Causes: - Insufficient permissions - Model not allowed - Budget/quota exceeded Solution: - Check IAM policy - Review usage limits - Contact admin for access

429 Rate Limit

Causes: - Too many requests - Burst limit exceeded Solution: - Implement exponential backoff - Request rate limit increase - Distribute load across time

Budget Exceeded

Causes:

Monthly/daily budget reached
Unexpected usage spike

Solution:

Review budget settings
Analyze usage patterns
Request budget increase
Use cost-optimized routing

Next Steps

Request Metadata

Track usage by user, team, or feature

Intelligent Routing

Optimize costs with smart routing

Self-Host

Deploy with your own security policies

Analytics Dashboard

Monitor key usage and costs

Get Started

Features

Integrations

Guides

Resources

Documentation Index

​Overview

Fine-Grained Access

Usage Limits

Audit Logs

IAM Rules

​Creating API Keys

​IAM-Style Access Control

​Allow Specific Models

​Restrict by Provider

​Time-Based Access

​Budget-Based Restrictions

​Usage Limits

​Rate Limiting

​Spending Limits

​Token Quotas

​Security Best Practices

​Production VISCA_API_KEY_PROD=vsk_prod_… ``` Configure different limits

​Audit Logging

​View Audit Logs

​Log Contents

​Multi-Tenant API Keys

​Organization-Level Keys

​Team-Level Keys

​User-Level Keys

​Temporary Keys

​IP Allowlisting

​Webhooks for Key Events

​Managing Keys Programmatically

​Create API Key

​List All Keys

​Revoke API Key

​Update Key Permissions

​Troubleshooting

​Next Steps

Request Metadata

Intelligent Routing

Self-Host

Analytics Dashboard

Overview

Creating API Keys

IAM-Style Access Control

Allow Specific Models

Restrict by Provider

Time-Based Access

Budget-Based Restrictions

Usage Limits

Rate Limiting

Spending Limits

Token Quotas

Security Best Practices

Production VISCA_API_KEY_PROD=vsk_prod_… ``` Configure different limits

Audit Logging

View Audit Logs

Log Contents

Multi-Tenant API Keys

Organization-Level Keys

Team-Level Keys

User-Level Keys

Temporary Keys

IP Allowlisting

Webhooks for Key Events

Managing Keys Programmatically

Create API Key

List All Keys

Revoke API Key

Update Key Permissions

Troubleshooting

Next Steps