Authentication & API Keys

API keys authenticate your requests to the Verbatik API. Rate limits protect the platform and ensure fair usage.

API Keys

Overview

API keys are scoped to a workspace. All members of a workspace can create and manage API keys. Each API key:

• Starts with the prefix vbt_ for easy identification.
• Is tied to a single workspace.
• Shares the workspace's balance and rate limits.
• Can optionally have an expiration date.

Creating an API Key

1. Go to API Keys in your workspace sidebar.
2. Click Create API Key.
3. Enter a descriptive name (e.g., "Production Server", "Development", "Mobile App").
4. Optionally set an expiration date.
5. Click Create.

After creation, only the key prefix (e.g., vbt_...abc) is shown for identification.

Using an API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer vbt_your_api_key_here

Deleting an API Key

Deleted keys are immediately revoked. Any requests using a deleted key will receive a 401 Unauthorized response.

Security Best Practices

• Never share API keys in public repositories, client-side code, or logs.
• Use different keys for different environments (development, staging, production).
• Set expiration dates for temporary keys.
• Rotate keys periodically.
• If a key is compromised, delete it immediately and create a new one.

Rate Limits

Default Rate Limits

Your workspace can make up to 100 API requests every 10 seconds across all API keys.

How Rate Limiting Works

• Uses a sliding window algorithm for smooth rate limiting.
• Applied per workspace, not per API key. All keys share the same pool.
• Different endpoints have independent limits (identifier combines endpoint type and key).

Rate Limit Headers

Every API response includes rate limit information:

Rate Limit Exceeded

{
  "success": false,
  "error": "Rate limit exceeded",
  "limit": 100,
  "remaining": 0,
  "reset": 1706123456789
}

Configuring Rate Limits

Workspace owners and members can customize rate limits:

1. Go to Settings or API Keys in your workspace sidebar.
2. Find the Rate Limit Settings section.
3. Configure:
   • Requests per window — Range: 1 to 10,000.
   • Time window (seconds) — Range: 0 to 3,600 seconds.
4. Save your settings.

Setting the time window to 0 seconds disables rate limiting entirely.

Handling Rate Limits in Code

Retry with backoff:

async function makeRequest(url, options) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return makeRequest(url, options);
  }
  
  return response;
}

Monitor remaining requests:

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');

if (remaining < 10) {
  await new Promise(resolve => setTimeout(resolve, 100));
}