Skip to main content
API keys authenticate your requests to agents through the Kovrex gateway. Each key is scoped to a specific agent subscription and can have its own rate limits and IP restrictions. You can create multiple keys per agent for different use cases:
  • Production — locked to your server IPs, higher rate limits
  • Development — unrestricted IPs, lower rate limits
  • Partner integrations — separate keys for each partner with their own limits

​
Creating an API Key

1

Navigate to API Keys

Go to Dashboard → API Keys and click Create API Key.
2

Select an agent

Choose which agent this key will access. You can only create keys for agents you have an active subscription to.
3

Configure the key

  • Name — A descriptive name (e.g., “Production Server”, “Dev Environment”)
  • Expiration — Optional expiration date
  • Rate limits — Custom per-minute and per-day limits, or use subscription defaults
  • IP restrictions — Lock the key to specific IPs or allow any IP
4

Copy your key

Your full API key is shown only once. Copy it immediately and store it securely.
kvx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Store your key securely. We only store a hash of your key and cannot retrieve or display it again. If you lose a key, you’ll need to regenerate it.

​
Using Your API Key

Include your API key in the Authorization header: 
curl -X POST https://gateway.kovrex.ai/v1/agents/{agent_id}/invoke \
  -H "Authorization: Bearer kvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "your request"}'
Or use the X-Kovrex-Key header: 
curl -X POST https://gateway.kovrex.ai/v1/agents/{agent_id}/invoke \
  -H "X-Kovrex-Key: kvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "your request"}'

​
IP Restrictions

IP restrictions limit which IP addresses can use a key. This is strongly recommended for production keys.

​
Adding IP Restrictions

You can specify:
  • Individual IPs — 192.168.1.100
  • CIDR ranges — 10.0.0.0/8 (allows 10.0.0.0 - 10.255.255.255)
Common CIDR ranges:
CIDRRangeUse case
/32Single IPOne server
/24256 IPsSmall subnet
/1665,536 IPsLarge network
/816.7M IPsCloud provider range

​
Best Practices

Do

  • Use IP restrictions for all production keys
  • Use CIDR ranges for dynamic cloud environments
  • Create separate keys for each environment

Don't

  • Use unrestricted keys in production
  • Share keys across teams or partners
  • Commit keys to version control

​
Unrestricted Keys

Keys without IP restrictions can be used from any IP address. Only use these for:
  • Local development
  • Environments where IP restrictions aren’t feasible
  • Testing and prototyping
Unrestricted keys are a security risk. If leaked, anyone can use them to make requests on your behalf.

​
Rate Limits

Rate limits protect both you and the agent operators from excessive usage.

​
How Rate Limits Work

Each key has two limits:
  • Per-minute — Maximum requests in a 60-second sliding window
  • Per-day — Maximum requests in a calendar day (UTC)
You can set custom limits per key, or use your subscription’s defaults.

​
Rate Limit Headers

Every response includes rate limit headers: 
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 45
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 8234
Use these headers to implement client-side throttling before hitting limits.

​
Handling Rate Limits

When you exceed a rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded (per minute)",
    "retry_after": 12
  }
}
Recommended handling: 
import time
import requests

def call_agent_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 10))
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

​
Managing Keys

​
Viewing Key Details

Go to Dashboard → API Keys to see all your keys with:
  • Usage stats (calls today, calls this month)
  • Last used timestamp
  • Configuration (rate limits, IP restrictions, expiration)

​
Updating a Key

You can update a key’s:
  • Name
  • Rate limits
  • IP restrictions
Changes take effect within 30 seconds.
You cannot change which agent a key is scoped to. Create a new key for a different agent.

​
Regenerating a Key

If a key is compromised or you need to rotate it:
  1. Click the ⋮ menu on the key card
  2. Select Regenerate
  3. Copy the new key immediately
The old key is revoked instantly. Update your applications with the new key.
Zero-downtime rotation: Create a new key first, update your applications, then revoke the old key.

​
Revoking a Key

To permanently disable a key:
  1. Click the ⋮ menu on the key card
  2. Select Revoke
Revoked keys cannot be restored. Any requests using the key will immediately receive a 401 Unauthorized response.

​
Error Responses

StatusCodeDescription
401missing_api_keyNo API key provided
401invalid_api_keyKey doesn’t exist or is malformed
401revoked_api_keyKey has been revoked
401expired_api_keyKey has passed its expiration date
403ip_not_allowedRequest IP not in key’s allowlist
403subscription_inactiveAgent subscription is not active
429rate_limit_minutePer-minute rate limit exceeded
429rate_limit_dayPer-day rate limit exceeded

​
Billing

API key usage is tracked for billing purposes. On the Billing page, you can see:
  • Total calls and cost per agent
  • Breakdown by individual key
  • Daily and monthly trends
This helps you attribute costs to specific projects, environments, or integrations.

​
Security Checklist

  • Use IP-restricted keys
  • Set appropriate rate limits
  • Store keys in environment variables or secrets manager
  • Never commit keys to version control
  • Use separate keys for each environment
  • Create separate keys for each team member or integration
  • Use descriptive names to track ownership
  • Revoke keys when team members leave
  • Review active keys quarterly
  • Monitor for unusual usage patterns
  • Have a process to quickly revoke compromised keys
  • Know how to regenerate keys without downtime

​
FAQ

There’s no hard limit on keys per agent. Create as many as you need for your use cases.
No, each key is scoped to a single agent. Create separate keys for each agent you subscribe to.
Expired keys stop working immediately. You’ll receive a 401 expired_api_key error. Create a new key to continue access.
Yes, the usage logs show the source IP for each request. Contact support for detailed access logs.
Create a new key, update your application to use both keys (fallback pattern), deploy, then revoke the old key.