Virtual API Keys

Create scoped API keys with granular permissions, model allow-lists, budgets, and rate limits. Every proxy request is checked against the key's permissions before reaching the provider.

Features

Endpoint Permissions

Each key has explicit permissions for which endpoints it can access: chat:write (/v1/chat/completions), embedding:write (/v1/embeddings), and run:write (/v1/run for image gen, STT, translation, etc.). Keys without the required permission receive a 403.

Model Allow-Lists

Restrict a key to specific models using exact names or wildcard patterns. For example, "gpt-4o*" allows gpt-4o and gpt-4o-mini but blocks claude-*. Empty list means all models allowed.

Budget Limits

Set a spending cap per key with configurable periods (daily, weekly, monthly). When the budget is reached, requests are blocked. Spend is tracked per-request across all endpoints.

Rate Limiting

Control requests per minute per key. Enforced on all proxy endpoints (/v1/chat/completions, /v1/embeddings, /v1/run). Prevents runaway costs from misbehaving applications.

Key Rotation

Rotate keys without downtime. Create a new key, update your apps, then revoke the old one.

Permission	Endpoint	Description
chat:write	/v1/chat/completions	Send chat completion requests to any configured provider
embedding:write	/v1/embeddings	Generate text embeddings via any provider
run:write	/v1/run	Run Workers AI specialized models (image gen, STT, translation, classification, etc.)
*	All endpoints	Wildcard — full access to all proxy endpoints and models

Code Examples

Create a restricted key (API)

# Create a key that can only use chat completions with GPT-4o models
curl https://api.cloudvera.io/keys \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frontend Chat Only",
    "permissions": ["chat:write"],
    "allowedModels": ["gpt-4o*", "gpt-4o-mini"],
    "rateLimitRpm": 30,
    "budgetUsd": 50
  }'

Permission denied response

// Key with only ["chat:write"] trying to call /v1/embeddings:
{
  "error": {
    "message": "Key does not have 'embedding:write' permission",
    "code": "permission_denied"
  }
}

// Key with allowedModels: ["gpt-4o*"] trying to use claude-sonnet:
{
  "error": {
    "message": "Model 'claude-sonnet-4-5-20250929' is not in this key's allowed models list",
    "code": "permission_denied"
  }
}