Authentication Guide

The CallCov API uses API keys to authenticate requests. This guide covers everything you need to know about securing your integration with our API.

Overview

All API requests must include your API key in the request headers. Your API key identifies your account and provides access to your resources.

Security Best Practice

Never expose your API keys in client-side code, public repositories, or version control systems. Always keep them secure on your server.

Getting Your API Key

1. Log in to your CallCov Dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy your key immediately (it won't be shown again)
5. Store it securely in your environment variables

Authentication Methods

API Key in Header (Recommended)

Include your API key in the X-API-Key header with every request:

import requests

API_KEY = "your_api_key_here"
API_URL = "https://api.callcov.com/api/v1"

headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json"
}

response = requests.get(
  f"{API_URL}/calls",
  headers=headers
)

print(response.json())

Environment Variables Best Practices

Store your API key as an environment variable to keep it secure:

import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

API_KEY = os.getenv("CALLCOV_API_KEY")

if not API_KEY:
  raise ValueError("CALLCOV_API_KEY environment variable not set")

# Use API_KEY in your requests
headers = {"X-API-Key": API_KEY}

Creating a Reusable Client

For production applications, create a reusable client class that handles authentication automatically:

import os
import requests
from typing import Optional, Dict, Any

class CallCovClient:
  """Reusable client for CallCov API"""

  def __init__(self, api_key: Optional[str] = None):
      self.api_key = api_key or os.getenv("CALLCOV_API_KEY")
      self.base_url = "https://api.callcov.com/api/v1"

      if not self.api_key:
          raise ValueError("API key is required")

      self.session = requests.Session()
      self.session.headers.update({
          "X-API-Key": self.api_key,
          "Content-Type": "application/json"
      })

  def get(self, endpoint: str, params: Optional[Dict] = None) -> Dict[Any, Any]:
      """Make a GET request"""
      url = f"{self.base_url}{endpoint}"
      response = self.session.get(url, params=params)
      response.raise_for_status()
      return response.json()

  def post(self, endpoint: str, data: Dict[Any, Any]) -> Dict[Any, Any]:
      """Make a POST request"""
      url = f"{self.base_url}{endpoint}"
      response = self.session.post(url, json=data)
      response.raise_for_status()
      return response.json()

# Usage
client = CallCovClient()
calls = client.get("/calls")
print(calls)

Testing Your Authentication

Verify your API key is working correctly with a simple test request:

import requests

def test_authentication(api_key):
  """Test if API key is valid"""
  headers = {"X-API-Key": api_key}

  try:
      response = requests.get(
          "https://api.callcov.com/api/v1/health",
          headers=headers,
          timeout=10
      )

      if response.status_code == 200:
          print("✓ Authentication successful!")
          return True
      elif response.status_code == 401:
          print("✗ Authentication failed - Invalid API key")
          return False
      else:
          print(f"✗ Unexpected response: {response.status_code}")
          return False

  except requests.exceptions.RequestException as e:
      print(f"✗ Connection error: {e}")
      return False

# Test your key
api_key = "your_api_key_here"
test_authentication(api_key)

Error Responses

401 Unauthorized

Your API key is missing or invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Solutions:

• Verify the API key is correct
• Check the header name is exactly X-API-Key
• Ensure there are no extra spaces or characters

403 Forbidden

Your API key is valid but lacks permission for this resource:

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions for this resource"
  }
}

Solutions:

• Check your account plan supports this feature
• Contact support if you believe this is an error

Security Best Practices

✅ Do's

• Store keys in environment variables, never in code
• Use HTTPS for all API requests
• Rotate keys regularly (every 90 days recommended)
• Use separate keys for development and production
• Monitor API usage for unusual patterns
• Revoke compromised keys immediately

❌ Don'ts

• Never commit keys to version control (Git, SVN, etc.)
• Never expose keys in client-side code (JavaScript, mobile apps)
• Never share keys via email or chat
• Never log API keys in application logs
• Never use the same key across multiple applications

Key Management

Rotating Keys

To rotate your API key safely:

1. Generate a new key in the dashboard
2. Update your production environment with the new key
3. Test the new key works correctly
4. Revoke the old key after confirming everything works

Revoking Keys

If you suspect a key has been compromised:

1. Immediately revoke the key in the dashboard
2. Generate a new key
3. Update all applications using the old key
4. Review API logs for suspicious activity

Rate Limits

All API keys have rate limits based on your plan:

Plan	Requests/Minute	Requests/Day
Free	10	1,000
Starter	60	10,000
Business	300	100,000
Enterprise	Custom	Custom

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699564800

Next Steps

• Make Your First Request
• Submit Call Analysis
• Handle Errors
• Production Best Practices

Need Help?

• Email: support@callcov.com
• Documentation: docs.callcov.com
• Dashboard: app.callcov.com