Catalog AI
Sign In

API Keys

Manage API keys for programmatic access to the platform.

Overview

API keys enable you to integrate the platform with your applications, automate workflows, and access all features programmatically.

Creating an API Key

  1. Navigate to API Keys in the sidebar
  2. Click Create New API Key
  3. Configure your key:
    • Name: Descriptive name (e.g., "Production Server", "Development")
    • Expiration (optional): Set an expiry date
  4. Click Create
  5. IMPORTANT: Copy and save your API key immediately - it's only shown once!

API Key Format

Generated keys follow this format:

apikey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys consist of:

  • Prefix: apikey_
  • Start: First few characters visible in UI
  • Full key: Hashed and stored encrypted in database

Using API Keys

Authentication Header

Include your API key in requests:

curl https://catalog-ai.tdcapps.com/api/products \
  -H "Authorization: Bearer apikey_your_key_here"

JavaScript/TypeScript

const response = await fetch('https://catalog-ai.tdcapps.com/api/products', {
  headers: {
    Authorization: 'Bearer apikey_your_key_here',
    'Content-Type': 'application/json'
  }
})

Python

import requests

headers = {
    'Authorization': 'Bearer apikey_your_key_here',
    'Content-Type': 'application/json'
}

response = requests.get('https://catalog-ai.tdcapps.com/api/products', headers=headers)

Rate Limiting

Control API usage with configurable rate limits.

Configuration

When creating or editing an API key, set:

  • Rate Limit Max: Maximum requests allowed in time window
  • Rate Limit Time Window: Duration in seconds
  • Remaining: Auto-calculated based on usage
  • Refill Interval: How often to reset limit (optional)
  • Refill Amount: How many requests to add on refill (optional)

Example Configuration

{
  rateLimitEnabled: true,
  rateLimitMax: 100,           // 100 requests
  rateLimitTimeWindow: 3600,   // per hour
  refillInterval: 3600,        // refill every hour
  refillAmount: 100            // add 100 requests
}

Rate Limit Headers

API responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When rate limit is exceeded, you'll receive:

Response:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "resetAt": "2024-01-15T15:00:00Z"
}

Status Code: 429 Too Many Requests

Best Practice:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options)

    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset')
      const waitTime = new Date(resetTime).getTime() - Date.now()
      await new Promise(resolve => setTimeout(resolve, waitTime))
      continue
    }

    return response
  }
  throw new Error('Max retries exceeded')
}

Auto-Refill

API keys can automatically refill request quotas.

How It Works

  1. Set refillInterval (e.g., 3600 seconds = 1 hour)
  2. Set refillAmount (e.g., 100 requests)
  3. Every interval, refillAmount is added to remaining
  4. Useful for continuous access without manual resets

Example Use Cases

Hourly Quota:

refillInterval: 3600 (1 hour)
refillAmount: 100
→ 100 requests per hour, automatically renewed

Daily Quota:

refillInterval: 86400 (24 hours)
refillAmount: 1000
→ 1000 requests per day, automatically renewed

Expiration

Set expiration dates for temporary or time-limited access.

Setting Expiration

When creating/editing a key:

{
  expiresAt: new Date('2024-12-31T23:59:59Z')
}

Behavior

  • Expired keys return 401 Unauthorized
  • Automatic expiration at specified time
  • Cannot be renewed (must create new key)
  • Useful for contractors, temporary integrations

Key Management

Viewing Keys

The API Keys page shows:

  • Key name
  • Start of key (first few characters)
  • Creation date
  • Last used timestamp
  • Request count
  • Remaining requests (if rate limited)
  • Expiration date
  • Enabled/disabled status

Editing Keys

You can update:

  • Key name
  • Rate limit settings
  • Expiration date
  • Enabled status

Cannot edit: The actual key value (create new if needed)

Disabling Keys

Temporarily disable without deletion:

  1. Go to API Keys
  2. Click on a key
  3. Toggle Enabled to off
  4. Disabled keys return 401 Unauthorized

Deleting Keys

Permanently remove an API key:

  1. Go to API Keys
  2. Click on a key
  3. Click Delete
  4. Confirm deletion
  5. WARNING: This action cannot be undone!

Usage Tracking

Request Count

Every API request increments:

  • requestCount: Total requests made with this key
  • Updates lastRequest: Timestamp of last usage

Monitoring Usage

View usage metrics:

  • Total requests
  • Last request time
  • Remaining quota (if rate limited)
  • Usage patterns over time

Security Best Practices

DO

✅ Store keys securely (environment variables, secret managers) ✅ Use different keys for development/production ✅ Set expiration dates for temporary access ✅ Enable rate limiting to prevent abuse ✅ Rotate keys periodically ✅ Monitor key usage for anomalies ✅ Disable unused keys immediately

DON'T

❌ Commit keys to version control (Git, etc.) ❌ Share keys in plain text (email, chat, docs) ❌ Use the same key across multiple services ❌ Store keys in client-side code ❌ Leave test/debug keys enabled in production

Key Rotation

Regularly rotate keys for security:

  1. Create a new API key
  2. Update your applications with the new key
  3. Test thoroughly
  4. Delete or disable the old key
  5. Recommended frequency: Every 90 days

Permissions (Future Feature)

Granular permissions will allow you to:

  • Read-only access
  • Specific resource access (products, jobs, etc.)
  • Operation limits (GET only, no DELETE)
  • Organization-scoped permissions

Currently, all API keys have full access to the organization's resources.

Troubleshooting

401 Unauthorized

Causes:

  • Invalid API key
  • Expired key
  • Disabled key
  • Incorrect Authorization header format

Solution:

# Correct format:
Authorization: Bearer apikey_xxxxx

# NOT:
Authorization: apikey_xxxxx
Authorization: Bearer xxxxx

429 Too Many Requests

Cause: Rate limit exceeded

Solution:

  • Wait for rate limit reset
  • Implement exponential backoff
  • Request higher rate limits
  • Create additional API keys

Key Not Working

Checklist:

  1. Key is enabled
  2. Key hasn't expired
  3. Using correct Authorization header
  4. API key belongs to correct organization
  5. Request URL is correct

Next Steps