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.

Monthly Quotas and Usage Tracking

API keys are subject to monthly quotas based on subscription tier:

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

Enterprise Tier

For organizations requiring advanced capabilities, our Enterprise tier offers:

• Custom API quotas - 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: Quota information is NOT included in regular API response headers to improve caching performance. To check your current usage and quota 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",
			"quota": 30000,
			"used": 1523,
			"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"
	}
}

Quota Exceeded

When quota is exceeded, requests will receive a 402 response:

{
	"error": {
		"code": "QUOTA_EXCEEDED",
		"message": "Monthly API quota exceeded",
		"details": {
			"quota": 30000,
			"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 quotas 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 402 Subscription Expired responses
• Usage tracking is real-time with periodic database synchronization

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