Skip to main content

Authentication

CallCov supports two authentication methods: API Keys (recommended for server-to-server) and JWT Tokens (for user-based applications).

API Key Authentication​

API keys are the recommended method for backend integrations. They're simple, secure, and don't expire.

Creating an API Key​

Create API Key
curl -X POST https://api.callcov.com/api/v1/api-keys/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server Key"
  }'

Using an API Key​

Include your API key in the Authorization header with the Bearer scheme:

Using API Key
curl -X GET https://api.callcov.com/api/v1/analysis/ \
  -H "Authorization: Bearer sk_live_abc123..."

API Key Format​

  • Prefix: sk_live_ for production, sk_test_ for test mode
  • Storage: Store securely in environment variables, never in code
  • Rotation: Regularly rotate keys for security
Best Practice

Store API keys in environment variables:

export CALLCOV_API_KEY="sk_live_abc123..."

JWT Token Authentication​

JWT tokens are ideal for user-facing applications where you need user-specific permissions.

Login Flow​

Step 1: Login
curl -X POST https://api.callcov.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}

Using JWT Tokens​

Step 2: Use Access Token
curl -X GET https://api.callcov.com/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Expiration​

  • Access Token: Expires in 30 minutes
  • Refresh Token: Expires in 7 days

Refreshing Tokens​

When your access token expires, use the refresh token to get a new one:

Refresh Access Token
curl -X POST https://api.callcov.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Security Best Practices​

1. Use HTTPS Only​

All API requests must use HTTPS. HTTP requests will be rejected.

2. Protect Your Keys​

# ✅ Good: Environment variable
export CALLCOV_API_KEY="sk_live_abc123..."

# ❌ Bad: Hardcoded in code
api_key = "sk_live_abc123..."  # Never do this!

3. Rotate Keys Regularly​

Create new API keys and revoke old ones every 90 days.

4. Use Different Keys for Different Environments​

# Development
sk_test_dev_abc123...

# Staging
sk_test_staging_def456...

# Production
sk_live_prod_ghi789...

5. Implement Token Refresh Logic​

Don't wait for 401 errors. Refresh proactively:

Python Example: Auto-Refresh
import requests
from datetime import datetime, timedelta

class CallCovClient:
    def __init__(self, email, password):
        self.email = email
        self.password = password
        self.access_token = None
        self.refresh_token = None
        self.token_expires = None
        self.login()

    def login(self):
        response = requests.post(
            'https://api.callcov.com/api/v1/auth/login',
            json={'email': self.email, 'password': self.password}
        )
        data = response.json()
        self.access_token = data['access_token']
        self.refresh_token = data['refresh_token']
        self.token_expires = datetime.now() + timedelta(seconds=data['expires_in'])

    def ensure_valid_token(self):
        # Refresh 5 minutes before expiration
        if datetime.now() >= self.token_expires - timedelta(minutes=5):
            self.refresh()

    def refresh(self):
        response = requests.post(
            'https://api.callcov.com/api/v1/auth/refresh',
            json={'refresh_token': self.refresh_token}
        )
        data = response.json()
        self.access_token = data['access_token']
        self.token_expires = datetime.now() + timedelta(seconds=data['expires_in'])

    def make_request(self, method, endpoint, **kwargs):
        self.ensure_valid_token()
        headers = kwargs.get('headers', {})
        headers['Authorization'] = f'Bearer {self.access_token}'
        kwargs['headers'] = headers
        return requests.request(method, f'https://api.callcov.com{endpoint}', **kwargs)

Revoking Access​

Revoke API Keys​

curl -X DELETE https://api.callcov.com/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Logout (Invalidate Tokens)​

JWT tokens cannot be revoked server-side but will expire automatically. For immediate logout, delete tokens client-side.

Authentication Errors​

Status CodeErrorSolution
401Invalid or missing tokenInclude valid Authorization header
401Token expiredRefresh your access token
403Insufficient permissionsCheck your account permissions

Next Steps​