How do API keys work?

API keys are your authentication credentials for accessing the Cathopic API. Understanding how they work is essential for secure and effective API integration.

What is an API key?

An API key is a unique secret token that identifies your application and authorizes it to access the Cathopic API:

• A long alphanumeric string (e.g., sk_live_abc123xyz789...)

• Acts as both authentication and authorization

• Tied to your Cathopic account and billing

• Can be active or inactive

Key lifecycle

Creation:

1. Generate keys in Settings → API

2. Give each key a descriptive name ("Production Website", "Staging", "Mobile App")

3. Copy the full key immediately - it's shown only once

4. Store securely (environment variables, secrets manager, password manager)

Usage:

• Include in the x-api-key HTTP header with every request

• Keys are validated server-side on each request

• All API usage is tracked and billed to your account

Deactivation:

• Keys can be temporarily disabled without deletion

• Useful for troubleshooting or pausing a specific integration

• Can be reactivated anytime

Deletion:

• Permanently removes the key

• Cannot be undone or recovered

• All requests with that key will fail immediately

Key management guidelines

Security:

• Never commit keys to version control: Use .env files and add them to .gitignore

• Never expose in client-side code: API keys should only be used server-side

• Use environment variables: Store keys in process.env.CATHOPIC_API_KEY or equivalent

• Rotate regularly: Change keys periodically (quarterly or after team member changes)

• Use separate keys per environment: Different keys for dev, staging, and production

Organization:

• Descriptive names: Name keys by purpose: "Production Website", "iOS App", "Email System"

• Document ownership: Track which team member created each key

• Regular audits: Review active keys monthly and remove unused ones

Multiple API keys

You can create multiple API keys for different purposes:

• Per environment: Separate keys for development, staging, production

• Per application: Different keys for website, mobile app, internal tools

• Per team member: Individual keys for developers (easier to track and revoke)

All keys under your account share the same billing. Usage from all keys is combined in your monthly invoice.

Monitoring key usage

Track activity for each key:

1. Go to Settings → API

2. View list of all keys with last used dates

3. Click on a key to see detailed usage statistics

4. Monitor for unexpected activity

What to do if a key is compromised

If you believe an API key has been exposed:

1. Immediately delete or deactivate the key in Settings → API

2. Generate a new replacement key

3. Update your application with the new key

4. Review usage logs for any suspicious activity

5. Contact support if you see unauthorized usage

Example: Storing keys securely

Node.js with environment variables:

// .env file (add to .gitignore!)
CATHOPIC_API_KEY=sk_live_abc123xyz789...
// Your code
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'Jesus' })
});

Python with environment variables:

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={'x-api-key': api_key},
    json={'query': 'Jesus'}
)