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 credits/month (5 requests/minute rate limit)
Plus: 30,000 credits/month ($49/month)
Pro: 200,000 credits/month ($299/month) (Recommended)
Business: 2,000,000 credits/month ($1,999/month)
Enterprise: Custom credit allocations (Contact sales)

Note: Credits are consumed based on endpoint complexity, not simple API call counts. Most endpoints cost 1-5 credits, with the enterprise batch endpoint offering significant savings at 35 credits for up to 50 CVEs.

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

Credit System

Your API key is associated with monthly credit limits based on your subscription tier:

Free: 1,000 credits/month (5 req/min rate limit)
Plus: 30,000 credits/month ($49/month)
Pro: 200,000 credits/month ($299/month) (Recommended)
Business: 2,000,000 credits/month ($1,999/month)
Enterprise: Custom credit allocations (Contact sales)

Credit Costs by Endpoint

Endpoint	Credits	Description
`/api/v1/ping`	0	Free healthcheck
`/api/v1/stats`	0.5	Platform statistics
`/api/v1/cves`	1	CVE search and listing
`/api/v1/cves/recent`	2	Recent CVE monitoring
`/api/v1/cve/{id}`	5	Single CVE details
`/api/v1/cve/batch`	35	Batch processing (1-50 CVEs, 86% savings)
`/api/v1/kev`	1	KEV catalog
`/api/v1/usage`	0	Usage monitoring

Managing Your Credits

import requests

class CreditAwareClient:
    def __init__(self, api_key, monthly_credits):
        self.api_key = api_key
        self.monthly_credits = monthly_credits
        self.credits_used = 0

    def make_request(self, url, expected_cost=1):
        if self.credits_used + expected_cost > self.monthly_credits:
            raise Exception("Monthly credit limit would be exceeded. Please upgrade your plan.")

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

        # Update credits based on actual cost (if available in headers)
        actual_cost = response.headers.get('X-Credits-Cost', expected_cost)
        self.credits_used += int(actual_cost)

        return response

    def get_usage(self):
        """Get current usage from API"""
        response = requests.get(
            "https://api.cybersecfeed.com/api/v1/usage",
            headers={"X-API-Key": self.api_key}
        )
        if response.status_code == 200:
            usage_data = response.json()['data']['usage']
            self.credits_used = usage_data['credits_used']
            return usage_data
        return None

Monitoring API Key Usage

Monitoring Your Usage

Check your current credit usage via the API:

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

This returns:

Total credits used this month
Remaining credits
Monthly credit limit
Reset date
Current plan details
Usage percentage

Checking Your Usage

To monitor your credit usage and 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 credits used
Monthly credit limit
Credits remaining
Percentage used
Reset date

Important: Credit 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.

Credit Usage Headers

Some endpoints may include credit information in response headers:

X-Credits-Cost: Credits consumed by current request
X-Credits-Remaining: Available credits until reset
X-Credits-Reset: Next reset date

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. "Credit Limit Exceeded"

Check your usage: curl -H "X-API-Key: your-key" https://api.cybersecfeed.com/api/v1/usage
Upgrade your plan for higher credit limits
Consider using the batch endpoint (35 credits for up to 50 CVEs vs 250 for individual calls)
For custom enterprise credit allocations, 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​

Credit System​

Credit Costs by Endpoint​

Managing Your Credits​

Monitoring API Key Usage​

Monitoring Your Usage​

Checking Your Usage​

Credit Usage Headers​

Rate Limit Headers (Free Tier Only)​

Troubleshooting​

Common Issues​

1. "Invalid API Key" Error​

2. "Credit Limit Exceeded"​

3. "Unauthorized" Despite Valid Key​

Debug Checklist​

API Key Lifecycle​

Generation​

Active Use​

Subscription Management​

Cancellation​

Summary​