Version: Next 🚧

Authentication & API Keys

The Cert-IX Scan API uses API keys for programmatic access. API keys provide granular scopes, scan type restrictions, per-key rate limits, IP allowlisting, automatic expiration, and zero-downtime rotation.

Authentication Methods

Method	Use Case	Header
API Key	Programmatic API access (scripts, CI/CD, integrations)	`X-API-Key`
JWT	Dashboard operations (API key management)	`Authorization: Bearer <token>`

This page covers API key authentication. JWT authentication is handled automatically by the Cert-IX Dashboard.

API Key Format

Cert-IX API keys follow a deterministic format for easy identification:

cix_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Segment	Description
`cix_`	Cert-IX platform prefix
`sk_`	Secret key type identifier
`XXX...`	40-character cryptographic random string

Security

API keys are hashed with SHA-256 before storage. The raw key is displayed only once at creation. Cert-IX cannot retrieve your key if lost — you must rotate.

Passing Your API Key

Include your API key in the X-API-Key header on every request:

curl -X GET https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: cix_sk_your_api_key_here"

Never pass API keys in URL query parameters

Query strings may be logged in server access logs, browser history, and proxy caches.

Creating an API Key

API keys are created via the Cert-IX Dashboard (JWT authentication).

Endpoint

POST /api/v1/api-keys

Request Body

{
  "name": "CI/CD Pipeline - Production",
  "description": "Used by GitHub Actions for nightly vulnerability scans",
  "scopes": [
    "scans:create",
    "scans:read",
    "scans:list",
    "results:read",
    "webhooks:read"
  ],
  "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
  "allowedIpAddresses": ["203.0.113.50", "198.51.100.0/24"],
  "rateLimitPerMinute": 30,
  "rateLimitPerHour": 500,
  "rateLimitPerDay": 5000,
  "expiresInDays": 90
}

Request Parameters

Field	Type	Required	Description
`name`	string	Yes	Human-readable key name (max 255 chars)
`description`	string	No	Optional usage description
`scopes`	string[]	No	Permission scopes (defaults to all scopes)
`allowedScanTypes`	string[]	No	Scan engines this key can invoke (defaults to all)
`allowedIpAddresses`	string[]	No	Source IP/CIDR ranges allowed to use this key
`rateLimitPerMinute`	integer	No	Max requests per minute
`rateLimitPerHour`	integer	No	Max requests per hour
`rateLimitPerDay`	integer	No	Max requests per day
`expiresInDays`	integer	No	Key expiration in days (`0` or `null` = no expiration)

Response (201 Created)

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "CI/CD Pipeline - Production",
      "keyPrefix": "cix_sk_001e3c",
      "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
      "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
      "status": "active",
      "expiresAt": "2026-06-04T10:00:00Z",
      "createdAt": "2026-03-06T10:00:00Z"
    },
    "rawKey": "cix_sk_001e3c2d92ffb23344a943df2b6a001fb1028d002"
  }
}

Critical

The rawKey field is returned only at creation. Copy it immediately and store it in a secure vault (e.g., HashiCorp Vault, AWS Secrets Manager, or your CI/CD secrets store).

Scopes & Permissions

Scopes control what actions an API key is authorized to perform. Apply the principle of least privilege — only grant the scopes your integration needs.

Available Scopes

Scope	Description
`scans:create`	Submit new scans
`scans:read`	View individual scan details and status
`scans:list`	List all tenant scans
`scans:cancel`	Cancel running scans
`results:read`	Retrieve scan results and findings
`templates:create`	Create scan templates
`templates:read`	View scan templates
`templates:update`	Modify scan templates
`templates:delete`	Delete scan templates
`webhooks:create`	Register and test webhooks
`webhooks:read`	View webhook configurations and delivery logs
`webhooks:update`	Modify webhook settings
`webhooks:delete`	Delete webhooks
`usage:read`	View usage analytics and quota information

Recommended Scope Sets

CI/CD Pipeline (scan read-write):

["scans:create", "scans:read", "scans:list", "results:read"]

Monitoring Dashboard (read-only):

["scans:read", "scans:list", "results:read", "usage:read"]

Full Automation (scans + webhooks + templates):

["scans:create", "scans:read", "scans:list", "scans:cancel", "results:read",
 "templates:create", "templates:read", "templates:update",
 "webhooks:create", "webhooks:read"]

Scope Enforcement

If a request requires a scope the API key doesn't have:

{
  "success": false,
  "error": "Insufficient scope: requires scans:create",
  "code": "INSUFFICIENT_SCOPE"
}

HTTP Status: 403 Forbidden

Allowed Scan Types

Restrict which scan engines an API key can invoke:

Isolate CI/CD keys to container scans only (e.g., trivy)
Limit OSINT keys to passive reconnaissance only (e.g., harvester, sublist3r)
Restrict web keys to web scanners (e.g., zap, nikto, wapiti)

Available scan types: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel

IP Allowlisting

Lock an API key to specific source IP addresses or CIDR ranges. Requests from other IPs are rejected with 403 IP_NOT_ALLOWED.

Supported formats:

Single IP: "203.0.113.50"
CIDR range: "198.51.100.0/24"
IPv6: "2001:db8::1"

Dynamic IPs

For CI/CD runners with dynamic IPs (e.g., GitHub Actions), omit allowedIpAddresses or use the runner's published CIDR ranges.

Rate Limits

Rate limits protect both your account and the platform. Limits are enforced across three windows:

Window	Default	Configurable Range
Per minute	60	1 – 1,000
Per hour	1,000	1 – 50,000
Per day	10,000	1 – 500,000

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1709654460

Rate Limit Exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Retry in 23 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}

HTTP Status: 429 Too Many Requests

Implement exponential backoff in your client:

import time

def api_call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response
        wait = 2 ** attempt  # 1s, 2s, 4s
        time.sleep(wait)
    raise Exception("Rate limit exceeded after retries")

Key Rotation

Rotate API keys with zero downtime using the grace period mechanism. During the grace period, both old and new keys are valid.

Endpoint

POST /api/v1/api-keys/:keyId/rotate

Request Body (optional)

{
  "gracePeriodHours": 24
}

Rotation Workflow

POST /api-keys/:oldKeyId/rotate     → New key created, old key enters grace period
Update your secrets store with the new key
Deploy the new key to your services
Old key automatically expires after the grace period

Best Practice

Rotate keys every 90 days. Automate rotation in your infrastructure or set a calendar reminder.

Key Revocation

Immediately and permanently disable an API key. Revocation is instant — the key stops working immediately with no grace period.

Endpoint

DELETE /api/v1/api-keys/:keyId

Request Body

{
  "reason": "Key compromised — rotating to new key"
}

After revocation, any request using the revoked key returns 401 KEY_REVOKED.

Key Statuses

Status	Description
`active`	Key is fully operational
`revoked`	Key has been permanently disabled
`expired`	Key has passed its `expiresAt` date
`suspended`	Key has been temporarily suspended by an admin

Only active keys can authenticate API requests.

Security Best Practices

Do

✅ Store keys in a secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)
✅ Use environment variables in your applications — never hardcode keys
✅ Apply least-privilege scopes — only grant what's needed
✅ Set expiration dates — rotate keys every 90 days
✅ Use IP allowlisting for static infrastructure
✅ Use per-key rate limits to prevent runaway automation
✅ Monitor usage via the usage analytics endpoints
✅ Revoke immediately if a key is compromised

Don't

❌ Never commit keys to source control (Git, SVN)
❌ Never pass keys in URL parameters
❌ Never share keys across teams or environments
❌ Never log API keys in application logs
❌ Never use a single key for all environments — create separate keys for dev, staging, production

Environment Variable Example

# .env (never committed to Git)
CERTIX_API_KEY=cix_sk_your_api_key_here

import os
api_key = os.environ["CERTIX_API_KEY"]

apiKey := os.Getenv("CERTIX_API_KEY")

const apiKey = process.env.CERTIX_API_KEY;

Next Steps:

Cette page vous a-t-elle été utile ?

Authentication Methods​

API Key Format​

Passing Your API Key​

Creating an API Key​

Endpoint​

Request Body​

Request Parameters​

Response (201 Created)​

Scopes & Permissions​

Available Scopes​

Recommended Scope Sets​

Scope Enforcement​

Allowed Scan Types​

IP Allowlisting​

Rate Limits​

Rate Limit Headers​

Rate Limit Exceeded​

Key Rotation​

Endpoint​

Request Body (optional)​

Rotation Workflow​

Key Revocation​

Endpoint​

Request Body​

Key Statuses​

Security Best Practices​

Do​

Don't​

Environment Variable Example​

Authentication Methods

API Key Format

Passing Your API Key

Creating an API Key

Endpoint

Request Body

Request Parameters

Response (201 Created)

Scopes & Permissions

Available Scopes

Recommended Scope Sets

Scope Enforcement

Allowed Scan Types

IP Allowlisting

Rate Limits

Rate Limit Headers

Rate Limit Exceeded

Key Rotation

Endpoint

Request Body (optional)

Rotation Workflow

Key Revocation

Endpoint

Request Body

Key Statuses

Security Best Practices

Do

Don't

Environment Variable Example