Skip to main content

​
API Key Authentication

ContentStats.io uses API keys to authenticate requests. Include your API key in the X-API-Key header for every request. 
curl https://contentstats.io/api/v1/videos \
  -H "X-API-Key: cs_live_YOUR_KEY"

​
Getting Your API Key

1

Access Dashboard

Go to Dashboard → API Keys
2

Create New Key

Click “Create New Key” and give it a descriptive name
3

Copy & Store

Copy the key immediately — it’s only shown once
Never expose your API key in client-side code, public repositories, or logs. Always use environment variables.

​
Key Formats

API keys come in two formats:
EnvironmentPrefixExample
Productioncs_live_cs_live_sk_abc123...
Testcs_test_cs_test_sk_xyz789...
Test keys are for development only. They work with the API but don’t charge your account.

​
Using API Keys

​
Environment Variables

Recommended approach — store keys in environment variables: 
CONTENTSTATS_API_KEY=cs_live_YOUR_KEY

​
Request Headers

All API requests require: 
X-API-Key: cs_live_YOUR_KEY
Content-Type: application/json
Example request: 
curl -X POST https://contentstats.io/api/v1/videos/track \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cs_live_YOUR_KEY" \
  -d '{
    "video_link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "duration_days": 7
  }'

​
Authentication Errors

​
401 Unauthorized

Missing or invalid API key: 
{
  "error": "API key required"
}
Fix: Ensure X-API-Key header is present and correctly formatted.

​
403 Forbidden

Valid key but insufficient permissions: 
{
  "error": "Access denied"
}
Fix: Check you’re accessing resources owned by your organization.

​
402 Payment Required

Insufficient balance: 
{
  "error": "Insufficient balance",
  "balance": 0.50,
  "estimated_cost": 2.52
}
Fix: Add credits to your account.

​
Security Best Practices

❌ Don’t do this:
const apiKey = 'cs_live_sk_abc123...'; // Hardcoded!
✅ Do this:
const apiKey = process.env.CONTENTSTATS_API_KEY;
Add .env to your .gitignore:
.gitignore
.env
.env.local
.env.production
Rotate API keys every 90 days or immediately if compromised:
  1. Create a new key
  2. Update your application
  3. Delete the old key
Never call the API from client-side JavaScript. Use a backend proxy:
// ❌ Don't expose API key in browser
fetch('https://contentstats.io/api/v1/videos', {
  headers: { 'X-API-Key': key } // Exposed to users!
});

// ✅ Call your own backend instead
fetch('/api/videos'); // Your backend handles API key
Monitor your keys in the Dashboard:
  • Last used timestamp
  • Request count
  • Associated resources

​
Managing Multiple Keys

You can create multiple API keys for:
  • Different environments (development, staging, production)
  • Team members (track usage per person)
  • Applications (separate keys per service)

​
Key Organization

# Development
CONTENTSTATS_API_KEY_DEV=cs_test_sk_dev123...

# Staging
CONTENTSTATS_API_KEY_STAGING=cs_live_sk_stg456...

# Production
CONTENTSTATS_API_KEY_PROD=cs_live_sk_prd789...

​
Rate Limiting

API keys are subject to rate limits based on your plan:
PlanRate Limit
Free60 requests/minute
Pro300 requests/minute
EnterpriseCustom
Rate limits are per API key. See Rate Limits for details.

​
Key Rotation Example

1

Create New Key

Generate a new key in the dashboard: cs_live_sk_NEW123...
2

Update Application

Update environment variable:
CONTENTSTATS_API_KEY=cs_live_sk_NEW123...
3

Deploy & Verify

Deploy changes and verify requests work with new key
4

Delete Old Key

Delete the old key from dashboard once confirmed working

​
Testing Your Authentication

Verify your API key works: 
curl https://contentstats.io/api/v1/usage \
  -H "X-API-Key: cs_live_YOUR_KEY"

{
  "balance_usd": 5.00,
  "total_snapshots": 0,
  "active_videos": 0,
  "estimated_snapshots_remaining": 333
}

​
Compromised Key?

If your API key is exposed:
  1. Delete it immediately in the Dashboard
  2. Create a new key
  3. Update your application
  4. Review usage logs for unauthorized activity
Deleted keys stop working immediately. Ensure you’ve updated your application before deleting.

​
Next Steps

API Reference

Explore all API endpoints

Error Handling

Handle authentication errors

Rate Limits

Understand rate limiting

Quickstart

Make your first API call