How do I authenticate requests? - Help Center

All requests to the Cathopic API must be authenticated using your API key. Here's how to properly authenticate your API calls.

Authentication method

The Cathopic API uses API key authentication via HTTP headers:

Header name: x-api-key
Header value: Your full API key
Required for: All API endpoints
Case sensitive: Header names and values must match exactly

Basic authentication example

cURL:

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Virgin Mary",
    "page": 1,
    "page_size": 20,
    "order": "popular"
  }'

JavaScript (fetch):

const response = await fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CATHOPIC_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Virgin Mary',
    page: 1,
    page_size: 20,
    order: 'popular'
  })
});
const data = await response.json();
console.log(data);

JavaScript (axios):

const axios = require('axios');
const response = await axios.post(
  'https://api.cathopic.com/resources',
  {
    query: 'Virgin Mary',
    page: 1,
    page_size: 20,
    order: 'popular'
  },
  {
    headers: {
      'x-api-key': process.env.CATHOPIC_API_KEY
    }
  }
);
console.log(response.data);

Python (requests):

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,
        'Content-Type': 'application/json'
    },
    json={
        'query': 'Virgin Mary',
        'page': 1,
        'page_size': 20,
        'order': 'popular'
    }
)
data = response.json()
print(data)

PHP (cURL):

 'Virgin Mary',
    'page' => 1,
    'page_size' => 20,
    'order' => 'popular'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
?>

Authentication errors

If authentication fails, you'll receive an error response:

Missing API key:

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Invalid API key:

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Inactive API key:

HTTP 401 Unauthorized
{
  "error": "Unauthorized token"
}

Important reminders

Security:

Never hardcode API keys: Use environment variables or secure configuration
Server-side only: Never include API keys in client-side JavaScript
Use HTTPS only: API keys transmitted over HTTP are vulnerable
Rotate regularly: Change keys periodically for security

Error handling:

Check status codes: Always verify the HTTP response status
Log authentication failures: Track failed attempts for security monitoring
Implement retry logic: With exponential backoff for transient errors
Validate before sending: Ensure API key is loaded correctly

Testing authentication

Quick test to verify your API key works:

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "page": 1, "page_size": 1}'

Expected response (success):

{
  "total": 1234,
  "page": 1,
  "page_size": 1,
  "results": [ ... ]
}

Common mistakes

Wrong header name: Must be x-api-key, not api-key or Authorization
Incorrect value format: Use the full key as-is, no "Bearer" prefix
Trailing whitespace: Trim API key values before using
Key not loaded: Check environment variable is correctly set

For troubleshooting authentication issues, see "Common authentication errors" in this section.