API Keys Documentation

Overview

CVEFinder.io provides API keys for Pro tier users to programmatically access the platform's features. API keys offer a secure, token-based authentication method for automated vulnerability scanning, CVE database queries, monitoring management, and exporting scan results.

Key Features

API Key Format

API keys follow this format:

cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456

Getting Started

Prerequisites

  1. Pro Tier Account: Upgrade your account to Pro tier at cvefinder.io/pricing
  2. Active Subscription: Your Pro subscription must be active

Authentication Methods

CVEFinder.io supports two authentication methods:

  1. JWT Token: For browser-based authentication (login via OTP)
  2. API Key: For programmatic access (server-to-server)

Creating an API Key

Endpoint

POST /api/create-api-key

Request Headers

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body

{
  "name": "CVEFinder CLI Tool"
}

Parameters:

Response (Success)

{
  "success": true,
  "api_key": "cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456",
  "api_key_id": 42,
  "name": "CVEFinder CLI Tool",
  "created_at": "2026-01-31 10:30:00"
}

IMPORTANT: Save the api_key value immediately. This is the only time the full key will be displayed. If you lose it, you'll need to rotate or create a new key.

Response (Error - Not Pro User)

{
  "success": false,
  "error": "API keys are only available for Pro users.",
  "upgrade_required": true,
  "upgrade_url": "/pricing"
}

Response (Error - Key Limit Reached)

{
  "success": false,
  "error": "Maximum of 5 API keys allowed per user"
}

cURL Example

curl -X POST https://cvefinder.io/api/create-api-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CVEFinder CLI Tool"}'

JavaScript Example

const response = await fetch('https://cvefinder.io/api/create-api-key', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'CVEFinder CLI Tool'
  })
});

const data = await response.json();
if (data.success) {
  console.log('API Key:', data.api_key);
  // Store this key securely - it won't be shown again!
}

Using Your API Key

Authentication Header

Include your API key in the Authorization header of all API requests:

Authorization: Bearer cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456

Example Requests

For complete API endpoint documentation, see the API Reference guide.

Scan a website:

curl -X POST https://cvefinder.io/api/scan \
  -H "Authorization: Bearer cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://example.com"}'

Get CVEs for a product with version filtering (Pro feature):

curl -X GET "https://cvefinder.io/api/product-cves?product_id=123&version=8.1.5&page=1&per_page=20&sort=epss" \
  -H "Authorization: Bearer cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456"

Get exploit information for a CVE (Pro feature):

curl -X GET "https://cvefinder.io/api/get-exploits?cve_id=456" \
  -H "Authorization: Bearer cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456"

See the API Reference for all available endpoints, request/response formats, and detailed documentation.

How It Works

  1. The API extracts the token from the Authorization: Bearer header
  2. If the token format matches an API key (cvf_ prefix, 52 chars), it validates against stored API keys
  3. The system securely verifies the key against stored hashes
  4. On successful validation, the request proceeds with the user's permissions
  5. Usage metrics are automatically updated

Managing API Keys

List Your API Keys

GET /api/list-api-keys

Response:

{
  "success": true,
  "keys": [
    {
      "id": 42,
      "masked_key": "cvf_a1b2c3•••••123456",
      "name": "CVEFinder CLI Tool",
      "requests_count": 1523,
      "last_used_at": "2026-01-31 14:22:15",
      "created_at": "2026-01-15 10:30:00"
    }
  ]
}

Revoke an API Key

Use this endpoint to permanently deactivate an API key.

Endpoint:

POST /api/revoke-api-key

Request Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body:

{
  "api_key_id": 42
}

Response (Success):

{
  "success": true,
  "message": "API key revoked successfully"
}

cURL Example:

curl -X POST https://cvefinder.io/api/revoke-api-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key_id": 42}'

Notes:

Rotate an API Key

Key rotation generates a new API key with the same name and automatically revokes the old one. This is useful for:

Endpoint:

POST /api/rotate-api-key

Request Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body:

{
  "api_key_id": 42
}

Response (Success):

{
  "success": true,
  "api_key": "cvf_new9876543210abcdefghijklmnopqrstuvwxyz012345",
  "api_key_id": 43,
  "name": "CVEFinder CLI Tool",
  "created_at": "2026-01-31 15:45:00"
}

cURL Example:

curl -X POST https://cvefinder.io/api/rotate-api-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key_id": 42}'

Important:

Security Best Practices

Storage

Example .env file:

CVEFINDER_API_KEY=cvf_a1b2c3d4e5f6789012345678901234567890abcdef123456

Access Control

Monitoring

Limitations

Error Codes

HTTP Code Error Description
401 Unauthorized No valid authentication provided
403 Forbidden Not a Pro user or insufficient permissions
400 Bad Request Invalid input (missing name, invalid ID, etc.)
404 Not Found API key doesn't exist or doesn't belong to your account
500 Server Error Internal server error

Usage Logging

Every API request is logged for analytics and security auditing:

Frequently Asked Questions

Can I use API keys for browser-based authentication?

No. API keys are designed for server-to-server communication. For browser-based apps, use JWT tokens obtained through the passwordless OTP login flow.

What happens if my Pro subscription expires?

Your API keys will stop working immediately when your subscription becomes inactive. They will resume working if you reactivate your Pro subscription.

Can I increase the 5-key limit?

The 5-key limit is currently fixed for all Pro users. If you need more keys, contact support@cvefinder.io to discuss enterprise options.

What Pro features can I access via API?

With API keys, you can access all Pro tier features:

Do API calls count toward my daily scan quota?

Yes. API scans count toward your 10 scans per day limit (same as web interface scans).

How are API keys stored?

API keys are cryptographically hashed before storage using industry-standard algorithms. The plaintext key is never stored in the database.

Can I regenerate a lost API key?

No. If you lose an API key, you must either rotate the existing key (if you know its ID) or revoke it and create a new one.

What's the difference between revoke and rotate?

Support

For issues or questions:

Changelog