Authentication Guide

This guide covers everything you need to know about authenticating with the CyberSecFeed API, including obtaining API keys, best practices for secure storage, and troubleshooting common authentication issues.

Overview

CyberSecFeed uses API key authentication to secure access to vulnerability data. Every request to the API must include a valid API key in the request headers.

Obtaining Your API Key

1. Select a Pricing Plan

Visit the CyberSecFeed website and select a pricing plan that meets your needs:

Free: 1,000 API calls/month (5 requests/minute rate limit)
Plus: 30,000 API calls/month
Premium: 100,000 API calls/month
Pro: 500,000 API calls/month (Recommended)
Enterprise: 2,000,000+ API calls/month

2. Complete Checkout

After selecting your plan:

Complete the secure checkout process via Stripe
Provide your email address for API key delivery
Your subscription will be activated immediately

3. Receive Your API Key

Your API key will be sent to your email address. Important:

Check your inbox (and spam folder) for the welcome email
Your API key is shown only once in this email
Copy it immediately and store it securely
If lost, contact [email protected] for assistance

Using Your API Key

Required Header

All API requests must include your API key in the X-API-Key header:

X-API-Key: your-api-key-here

Example Request

curl -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/ping

Authentication Errors

If your API key is missing or invalid, you'll receive a 401 Unauthorized response:

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Invalid or missing API key"
	},
	"meta": {
		"timestamp": "2024-01-25T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

API Key Best Practices

1. Environment Variables

Never hardcode API keys in your source code. Use environment variables instead:

Linux/macOS

export CYBERFEED_API_KEY="your-api-key-here"

Windows

$env:CYBERFEED_API_KEY = "your-api-key-here"

Python Example

import os
import requests

api_key = os.environ.get('CYBERFEED_API_KEY')
if not api_key:
    raise ValueError("CYBERFEED_API_KEY environment variable not set")

headers = {"X-API-Key": api_key}
response = requests.get(
    "https://api.cybersecfeed.com/api/v1/ping",
    headers=headers
)

2. Secrets Management

For production environments, use proper secrets management:

AWS Secrets Manager

import boto3
import json

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

Azure Key Vault

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

def get_api_key():
    credential = DefaultAzureCredential()
    client = SecretClient(
        vault_url="https://your-vault.vault.azure.net/",
        credential=credential
    )
    return client.get_secret("cyberfeed-api-key").value

HashiCorp Vault

# Store the key
vault kv put secret/cyberfeed api_key="your-api-key-here"

# Retrieve in application
vault kv get -field=api_key secret/cyberfeed

3. Configuration Files

If you must use configuration files:

.env file (with python-dotenv)

# .env file (add to .gitignore!)
CYBERFEED_API_KEY=your-api-key-here

from dotenv import load_dotenv
import os

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

NEVER commit these files:

# .gitignore
.env
config.json
secrets.yml
*.key

4. CI/CD Pipelines

Configure API keys as secure environment variables in your CI/CD system:

GitHub Actions

- name: Test API Integration
  env:
    CYBERFEED_API_KEY: ${{ secrets.CYBERFEED_API_KEY }}
  run: python test_api.py

GitLab CI

test:
  script:
    - python test_api.py
  variables:
    CYBERFEED_API_KEY: $CYBERFEED_API_KEY

API Key Security

Do's ✅

Rotate Keys Regularly: Generate new keys every 90 days
Use Different Keys: Separate keys for development, staging, and production
Monitor Usage: Check your dashboard for unexpected usage patterns
Limit Scope: Use API keys with minimal required permissions
Secure Storage: Use environment variables or secrets management
HTTPS Only: Always use HTTPS for API requests

Don'ts ❌

Never share keys: Each developer should have their own key
Never commit to Git: Use .gitignore for any files containing keys
Never expose in browsers: Don't use API keys in client-side JavaScript
Never email keys: Use secure channels for key distribution
Never log keys: Ensure keys aren't written to log files
Never use in URLs: Keys should only be in headers, not query parameters

Managing Multiple API Keys

Managing Your API Key

Since API keys are automatically generated:

Use environment variables to distinguish between environments
Keep separate subscriptions for production and development
Document which email/subscription each key belongs to

Key Rotation Strategy

# Example: Graceful key rotation
import os
import requests
from datetime import datetime

class APIClient:
    def __init__(self):
        # Try primary key first, fallback to secondary
        self.primary_key = os.environ.get('CYBERFEED_API_KEY_PRIMARY')
        self.secondary_key = os.environ.get('CYBERFEED_API_KEY_SECONDARY')
        self.current_key = self.primary_key

    def make_request(self, endpoint):
        headers = {"X-API-Key": self.current_key}
        response = requests.get(
            f"https://api.cybersecfeed.com/api/v1{endpoint}",
            headers=headers
        )

        # If primary key fails, try secondary
        if response.status_code == 401 and self.current_key == self.primary_key:
            self.current_key = self.secondary_key
            headers = {"X-API-Key": self.current_key}
            response = requests.get(
                f"https://api.cybersecfeed.com/api/v1{endpoint}",
                headers=headers
            )

        return response

API Quotas

Your API key is associated with monthly usage quotas based on your subscription tier:

Free: 1,000 API calls/month (5 req/min rate limit)
Plus: 30,000 API calls/month
Premium: 100,000 API calls/month
Pro: 500,000 API calls/month (Recommended)
Enterprise: 2,000,000+ API calls/month

Managing Your Quota

import requests

class QuotaAwareClient:
    def __init__(self, api_key, monthly_quota):
        self.api_key = api_key
        self.monthly_quota = monthly_quota
        self.calls_this_month = 0

    def make_request(self, url):
        if self.calls_this_month >= self.monthly_quota:
            raise Exception("Monthly quota exceeded. Please upgrade your plan.")

        response = requests.get(url, headers={"X-API-Key": self.api_key})
        self.calls_this_month += 1

        return response

Monitoring API Key Usage

Monitoring Your Usage

Check your current usage via the API:

curl -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/usage

This returns:

Total API calls this month
Remaining quota
Reset date
Current plan details

Checking Your Usage

To monitor your API usage and quota limits, use the dedicated usage endpoint:

curl -H "X-API-Key: YOUR_API_KEY" \
     https://api.cybersecfeed.com/api/v1/usage

This returns detailed usage information including:

Current usage count
Monthly quota limit
Percentage used
Reset date

Important: Quota information is only available through the /api/v1/usage endpoint. It is not included in regular API response headers to enable better caching and performance.

Rate Limit Headers (Free Tier Only)

Free tier responses include rate limiting information:

X-Rate-Limit-Remaining: Requests remaining in current minute
X-Rate-Limit-Reset: Unix timestamp when rate limit resets

Troubleshooting

Common Issues

1. "Invalid API Key" Error

Verify key is copied correctly (no extra spaces)
Check if key is active in dashboard
Ensure using correct environment (production vs development)

2. "Quota Exceeded"

Check your usage: curl -H "X-API-Key: your-key" https://api.cybersecfeed.com/api/v1/usage
Upgrade your plan at https://cybersecfeed.com/pricing
For custom enterprise quotas, contact [email protected]

3. "Unauthorized" Despite Valid Key

Verify header name is exactly X-API-Key
Check for typos in the header
Ensure key hasn't expired or been revoked

Debug Checklist

# 1. Test your API key
curl -v -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/ping

# 2. Check headers are sent correctly
curl -v -H "X-API-Key: your-api-key-here" \
     https://api.cybersecfeed.com/api/v1/ping 2>&1 | grep "X-API-Key"

# 3. Verify key format (UUID-UUID format, 72 characters)
echo "your-api-key-here" | grep -E "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"

API Key Lifecycle

Generation

API keys are automatically generated upon subscription
Sent via email to the subscription owner
Active immediately upon creation

Active Use

Monitor usage via /api/v1/usage endpoint periodically
Set up automated checks if approaching limits
Watch for rate limit headers (Free tier only)
Consider upgrading if consistently hitting limits

Subscription Management

Manage your subscription via Stripe Customer Portal
Upgrade/downgrade takes effect immediately
API key remains the same across plan changes

Cancellation

Cancel via Stripe Customer Portal
API key disabled at end of billing period
Contact support for immediate revocation if needed

Summary

Proper API key management is crucial for:

Security: Protecting your account and data
Reliability: Ensuring uninterrupted service
Compliance: Meeting security requirements
Cost Control: Monitoring and optimizing usage

Follow these guidelines to maintain secure and efficient access to CyberSecFeed's vulnerability intelligence.

Overview​

Obtaining Your API Key​

1. Select a Pricing Plan​

2. Complete Checkout​

3. Receive Your API Key​

Using Your API Key​

Required Header​

Example Request​

Authentication Errors​

API Key Best Practices​

1. Environment Variables​

Linux/macOS​

Windows​

Python Example​

2. Secrets Management​

AWS Secrets Manager​

Azure Key Vault​

HashiCorp Vault​

3. Configuration Files​

.env file (with python-dotenv)​

NEVER commit these files:​

4. CI/CD Pipelines​

GitHub Actions​

GitLab CI​

API Key Security​

Do's ✅​

Don'ts ❌​

Managing Multiple API Keys​

Managing Your API Key​

Key Rotation Strategy​

API Quotas​

Managing Your Quota​

Monitoring API Key Usage​

Monitoring Your Usage​

Checking Your Usage​

Rate Limit Headers (Free Tier Only)​

Troubleshooting​

Common Issues​

1. "Invalid API Key" Error​

2. "Quota Exceeded"​

3. "Unauthorized" Despite Valid Key​

Debug Checklist​

API Key Lifecycle​

Generation​

Active Use​

Subscription Management​

Cancellation​

Summary​