Skip to main content

Create API Key

Creates a new API key for programmatic access to the CallCov API. The full API key is only shown once during creation and cannot be retrieved later.

Endpoint​

POST /api/v1/api-keys/

Authentication​

Requires JWT token (Bearer authentication).

JWT Only

API keys can only be created using JWT authentication. You cannot create an API key using another API key.

Request​

Content-Type​

application/json

Request Body​

FieldTypeRequiredDescription
descriptionstringNoDescription of what this key is for (max 500 chars)

Example Request​

{
  "description": "Production API key for call analysis integration"
}

Response​

Success Response (201 Created)​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "key_prefix": "sk_live_abc123",
  "description": "Production API key for call analysis integration",
  "created_at": "2024-01-15T10:30:00Z"
}
Save Your API Key!

The api_key value is only shown once. Save it immediately in a secure location. You will not be able to retrieve it again.

Response Fields​

FieldTypeDescription
idUUIDUnique API key identifier
api_keystringFull API key (shown only once!)
key_prefixstringFirst 14 characters of the key (for identification)
descriptionstringYour description
created_atdatetimeCreation timestamp (ISO 8601)

API Key Format​

API keys follow the format: sk_{environment}_{random_string}

  • sk = Secret Key
  • live = Production environment
  • test = Test environment (not implemented yet)
  • Random string = 48 characters

Example: sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Limits​

  • Maximum 10 active API keys per user
  • To create more, you must expire unused keys first

Examples​

curl -X POST https://api.callcov.com/api/v1/api-keys/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
  "description": "Production API key"
}'

Using Your API Key​

After creating an API key, use it for API authentication:

# Instead of JWT token
curl https://api.callcov.com/api/v1/analysis/ \
  -H "X-API-Key: sk_live_abc123def456..."

Errors​

400 Bad Request​

Maximum API keys reached:

{
  "detail": "Maximum number of API keys (10) reached. Please expire unused keys."
}

401 Unauthorized​

Invalid or missing JWT token:

{
  "detail": "Could not validate credentials"
}

Security Best Practices​

✅ DO​

  • Save immediately: Copy the key to a secure password manager
  • Use environment variables: Store in .env files (never commit!)
  • Rotate regularly: Create new keys periodically and expire old ones
  • Use descriptive names: Helps identify which integration uses which key
  • Separate keys per environment: Different keys for dev, staging, production

❌ DON'T​

  • Never commit to Git: API keys in code = security breach
  • Never share publicly: Don't paste in Slack, Discord, forums
  • Never log in plaintext: Redact keys in application logs
  • Never embed in client-side code: Only use on backend/server

Example: Secure Storage​

Environment Variable (.env file)​

# .env (add to .gitignore!)
CALLCOV_API_KEY=sk_live_abc123def456...
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('CALLCOV_API_KEY')

AWS Secrets Manager​

import boto3
import json

def get_api_key():
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId='callcov/api-key')
    return json.loads(response['SecretString'])['api_key']

api_key = get_api_key()

Organizing Multiple Keys​

Create different keys for different purposes:

# Development
description="Development - Local Testing"

# Staging
description="Staging - QA Environment"

# Production
description="Production - Main Application"

# CI/CD
description="CI/CD - Automated Tests"

This makes it easy to:

  • Identify which key is being used
  • Expire compromised keys without affecting others
  • Track usage per environment

What Happens After Creation​

  1. Full key returned: Save it immediately
  2. Key is hashed: Only hash is stored in database
  3. Prefix saved: Used for identification in key list
  4. Key is active: Can be used immediately for API requests

Key Lifecycle​

Create Key → Use for API calls → Monitor usage → Expire when no longer needed