API Keys & IAM Rules

API keys are the primary method for authenticating with the doteb. This guide covers creating API keys, managing them, and configuring IAM rules for fine-grained access control.

Overview

doteb provides comprehensive API key management with the following features:

• Basic API Key Management: Create, list, update, and delete API keys
• Usage Limits: Set lifetime and recurring spending limits on individual API keys
• Expiration (TTL): Give a key a time-to-live so it disables itself automatically
• IAM Rules: Fine-grained access control for models, providers, and pricing
• Usage Tracking: Monitor API key usage and costs
• Status Management: Enable/disable keys without deletion

Creating API Keys

Via Dashboard

At this time, API keys can only be created via the dashboard.

1. Navigate to your project in the doteb dashboard
2. Go to the API Keys section
3. Click Create API Key
4. Provide a description for your key
5. Optionally set an all-time usage limit
6. Optionally set a recurring usage limit such as $10 / day or $500 / month
7. Optionally set an expiration (TTL) such as 30 minutes, 12 hours, or 7 days
8. Click Create

Using API Keys

Once you have an API key, use it in the Authorization header of your requests:

curl -X POST "https://api.doteb.com/v1/chat/completions" \
  -H "Authorization: Bearer llmgtwy_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Disabling/Enabling API Keys

You can disable an API key to stop it from being used, but the key is not deleted and can be re-enabled later.

Expiration (TTL)

You can give an API key a time-to-live (TTL) when you create it. Set how long the key should live — in minutes, hours, or days — and it will be disabled automatically once that time passes. This is ideal for short-lived integrations, demos, CI jobs, and temporary access.

• A key works normally until its expiration time
• Once expired, the gateway rejects requests with that key with a 401 Unauthorized
• A background job marks expired keys as inactive, so the dashboard reflects the disabled state
• Keys created without a TTL never expire (the default)

Reactivating an Expired Key

An expired key is paused, not deleted. To bring it back online you must reactivate it with a new future expiration — an expired key cannot be re-enabled while its TTL is still in the past. Keys that have no TTL, or whose TTL is still in the future, can be enabled and disabled freely without setting a new expiration.

Usage Limits

Usage is tracked per API key on the API Keys page. Usage includes both costs from doteb credits and usage from your own provider keys when applicable, giving you complete visibility into total spending per key.

You can set two independent limits for each key:

• All-time usage limit: A lifetime spend cap
• Recurring usage limit: A spend cap that resets every configured hour, day, week, or month

When a key reaches either limit, requests using that key return 401 Unauthorized until the key is updated or, for recurring limits, the next usage window starts. This is separate from IAM rule violations, which return 403 Forbidden.

Recurring windows support:

• Minimum duration: 1 hour
• Maximum duration: 12 months
• Units: hour, day, week, month

For the dashboard walkthrough and field-by-field details, see API Keys in Learn.

IAM Rules

IAM (Identity Access Management) rules provide fine-grained access control over what models, providers, and pricing tiers an API key can access.

Rule Types

Model Access Rules

Control access to specific models:

• Allow Models: Only allow access to specific models
• Deny Models: Block access to specific models

Provider Access Rules

Control access to specific providers:

• Allow Providers: Only allow access to specific providers
• Deny Providers: Block access to specific providers

Pricing Rules

Control access based on model pricing:

• Allow Pricing: Set constraints on what pricing tiers are allowed
• Deny Pricing: Block specific pricing tiers
• Free vs Paid: Allow or deny access to free vs paid models

IP Address Rules

Restrict where the API key can be used from by source IP, using CIDR ranges:

• Allow IP Ranges (CIDR): Only permit requests from the listed IPv4/IPv6 CIDRs
• Deny IP Ranges (CIDR): Block requests from the listed IPv4/IPv6 CIDRs

Both IPv4 (e.g. 192.0.2.0/24) and IPv6 (e.g. 2001:db8::/32) ranges are supported, and you can mix both in a single rule. To restrict to a single address, use a /32 (IPv4) or /128 (IPv6) prefix.

The gateway reads the client IP from the first entry in the X-Forwarded-For header (set by the GCP load balancer). When an allow_ip_cidrs rule is configured and the gateway cannot determine the client IP, the request is denied. Invalid CIDR syntax is rejected at rule-creation time with a 400 error.

Error Handling

When API keys encounter IAM rule violations, the API returns a 403 with the standard OpenAI error envelope:

{
	"error": {
		"message": "Access denied: Model gpt-4 is not in the allowed models list",
		"type": "invalid_request_error",
		"param": null,
		"code": "permission_denied"
	}
}

Common error scenarios:

• Model not allowed by IAM rules
• Provider blocked by IAM rules
• Pricing limits exceeded
• API key disabled or deleted
• API key expired (TTL passed)
• Usage limit reached

Migration from Legacy Keys

If you have existing API keys without IAM rules:

1. Backward Compatibility: Existing keys continue to work without restrictions
2. Gradual Migration: Add IAM rules incrementally
3. Testing: Test IAM rules in development before applying to production
4. Monitoring: Monitor for access denied errors after implementing rules