Authentication Reference

This page provides technical details about API authentication. For a complete guide including obtaining keys and best practices, see the Authentication Guide.

Authentication Method

CyberSecFeed API uses API key authentication. Every request must include a valid API key in the request headers.

Required Header

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

Example Requests

cURL

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

Python

import requests

headers = {
    "X-API-Key": "your-api-key-here"
}

response = requests.get(
    "https://api.cybersecfeed.com/api/v1/ping",
    headers=headers
)

JavaScript

const response = await fetch('https://api.cybersecfeed.com/api/v1/ping', {
	headers: {
		'X-API-Key': 'your-api-key-here',
	},
});

Authentication Errors

Missing API Key

Request without API key:

curl https://api.cybersecfeed.com/api/v1/ping

Response:

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Missing API key",
		"details": "Please provide X-API-Key header"
	},
	"meta": {
		"timestamp": "2025-07-20T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

HTTP Status: 401 Unauthorized

Invalid API Key

Request with invalid key:

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

Response:

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Invalid API key"
	},
	"meta": {
		"timestamp": "2025-07-20T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

HTTP Status: 401 Unauthorized

Expired Subscription

Response:

{
	"error": {
		"code": "SUBSCRIPTION_EXPIRED",
		"message": "Subscription expired. Your subscription was cancelled and the billing period has ended"
	},
	"meta": {
		"timestamp": "2025-07-20T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

HTTP Status: 401 Unauthorized

API Key Format

• API keys follow UUID-UUID format with SHA-256 hashing for security
• Case-sensitive
• Exactly 72 characters long (including hyphens)
• Automatically delivered via email after subscription activation
• Example format: a1b2c3d4-e5f6-7890-abcd-ef1234567890-98765432-dcba-4321-9876-543210fedcba
• Keys are stored securely using SHA-256 hashing with salt

Security Requirements

1. HTTPS Only: All requests must use HTTPS. HTTP requests will be rejected.
2. Header Only: API keys must only be sent in headers, never in URLs or request bodies.
3. No Client-Side: Never use API keys in client-side code (browser JavaScript, mobile apps).

API Key Scopes

All API keys have full read access to all endpoints. There are no restricted scopes.

Credit System and Usage Tracking

API keys are subject to monthly credit limits based on subscription tier. Each endpoint consumes credits based on computational cost and value delivered:

Tier	Monthly Credits	Price	Rate Limit	Support Level
Free	1,000 credits	Free	5 req/minute	Community forums
Plus	30,000 credits	$49/month	No limit	Email support (24h)
Pro	200,000 credits	$299/month	No limit	Priority support (8h)
Business	2,000,000 credits	$1,999/month	No limit	Dedicated support
Enterprise	Custom credits	Contact us	No limit	Custom SLA & features

Credit Costs per Endpoint

Endpoint	Credits	Description
/api/v1/ping	0	Free healthcheck
/api/v1/ping-lite	0	Free healthcheck
/api/v1/stats	0.5	Minimal statistics
/api/v1/cves	1	List operations
/api/v1/cves/recent	2	Recent monitoring
/api/v1/cve/{id}	5	Single CVE detail
/api/v1/cve/batch	35	Batch up to 50 CVEs (86% savings)
/api/v1/kev	1	KEV list
/api/v1/kev/{id}	3	KEV detail
/api/v1/usage	0	Free monitoring

Enterprise Tier

For organizations requiring advanced capabilities, our Enterprise tier offers:

• Custom credit allocations - Unlimited or tailored to your specific volume requirements
• Custom SLA agreements - Guaranteed 99.99%+ uptime with penalty clauses
• Additional enrichment data - Access to proprietary threat intelligence feeds
• Private data feeds - Exclusive vulnerability intelligence not available in standard tiers
• Dedicated infrastructure - Isolated deployment with dedicated resources
• Custom integrations - Tailored API endpoints, data formats, and delivery methods
• Priority feature development - Influence product roadmap for your use cases
• On-premises deployment - Private cloud or on-site installation options

Contact: For Enterprise pricing and custom solutions, contact our sales team at [email protected]

Checking Your Usage

Important: Credit information is NOT included in regular API response headers to improve caching performance. To check your current usage and credit limits, use the dedicated usage endpoint:

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

Response:

{
	"data": {
		"usage": {
			"plan": "CyberSecFeed Plus",
			"credits_limit": 30000,
			"credits_used": 1523,
			"credits_remaining": 28477,
			"reset_at": "2025-08-01T00:00:00Z",
			"percentage_used": 5.08
		}
	},
	"meta": {
		"timestamp": "2025-07-20T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

Credit Usage Response Headers

Some endpoints include credit usage information in response headers:

• X-Credits-Limit: Total monthly credit allocation
• X-Credits-Used: Credits consumed this billing period
• X-Credits-Remaining: Available credits until reset
• X-Credits-Cost: Credits consumed by current request
• X-Credits-Reset: Next reset date (ISO 8601 format)

Credit Limit Exceeded

When monthly credit limit is exceeded, requests will receive a 429 response:

{
	"error": {
		"code": "CREDIT_LIMIT_EXCEEDED",
		"message": "Monthly credit limit exceeded. Upgrade your plan or wait for reset.",
		"details": {
			"credits_limit": 30000,
			"credits_used": 30001,
			"reset_at": "2025-08-01T00:00:00Z"
		}
	},
	"meta": {
		"timestamp": "2025-07-20T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

Rate Limiting (Free Tier Only)

For Free tier rate limiting, you'll receive a 429 response:

{
	"error": {
		"code": "RATE_LIMITED",
		"message": "Rate limit exceeded (5 requests per minute)",
		"details": {
			"limit": 5,
			"window": "1 minute",
			"retry_after": 45
		}
	},
	"meta": {
		"timestamp": "2025-07-20T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

Rate limit headers (Free tier only):

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

Testing Authentication

Use the ping endpoint to test your API key:

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

A successful response confirms your API key is valid and active.

Subscription Management

Billing Periods and Resets

• Monthly credits reset on the same day each month based on your subscription start date
• Cancelled subscriptions continue working until the end of the current billing period
• Expired subscriptions (billing period ended) receive 401 Subscription Expired responses
• Credit tracking is real-time with atomic updates and periodic database synchronization
• Credit consumption is calculated per request based on endpoint cost

Support Tiers

Each subscription tier includes different support levels:

• Community (Free): Access to community forums and documentation
• Email Support (Plus): Email support with 24-hour response time
• Priority Support (Pro): Priority email support with 8-hour response time
• Dedicated Support (Business): Dedicated support team with direct contact
• Enterprise Support: Custom SLA with guaranteed response times, dedicated account manager, and priority escalation

Grace Periods

• Cancelled subscriptions: Access continues until the end of the current billing period
• Failed payments: 72-hour grace period before suspension
• Account reactivation: Immediate upon successful payment processing