Authentication and API keys.

// Section 01 · Authorization header

Bearer token format and request structure.

Every authenticated API request must include an Authorization header with a valid API key. The format follows RFC 6750: Bearer token. Content-Type for any POST or PUT body must be application/json.

Authorization: Bearer crl_live_8f3k29vJ7nQa4b8c92eP3kqM
Content-Type: application/json

Keys come in two environments: crl_test_ for sandbox testing and crl_live_ for production audits. The prefix tells you immediately which environment a key belongs to, which prevents the common pattern of accidentally hitting production with test code or vice versa.

// Section 02 · Test mode

Test mode is free and returns realistic synthetic data.

Test mode keys (crl_test_) return realistic but synthetic audit data without consuming quota. The synthetic data follows the same JSON schema as live audits including score distributions, findings arrays and analyzer codes. Useful for building integrations without paying for real audits during development.

What test mode returns: deterministic synthetic audits keyed by domain string. Calling POST /audits twice with the same test key and same domain returns the same audit_id and same findings. This makes integration tests reproducible. Live mode is different: every audit triggers a real crawl and produces a new audit_id.

What test mode does not include: webhook callbacks to your endpoint (test webhooks are sent to a mock URL that returns 200 instantly so retry logic does not engage), PDF generation (synthetic PDFs return a stub document with the same schema as real PDFs), and rate limiting (test mode is unrestricted).

// Section 03 · Key management

Generating, rotating and revoking keys.

Keys are generated from the Crawlux dashboard under Settings → API Keys. Each workspace can have unlimited keys. At creation time, the key is displayed once. Crawlux does not store the key in plaintext, so it cannot be retrieved after creation. Store it in a secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, environment variables in your CI/CD platform) before closing the creation dialog.

Rotation is supported. Generate a new key, update your applications to use it, then revoke the old key. Crawlux does not enforce rotation cadence but recommends quarterly rotation for production keys. Compromised keys should be revoked immediately from the dashboard; the revocation takes effect within 30 seconds.

// Section 04 · Webhook signatures

Webhooks use a separate signing secret.

Webhook callbacks use HMAC-SHA256 signature verification, separate from API key authentication. The signing secret is configured per webhook (auto-generated at webhook creation, displayed once) and used to compute the X-Crawlux-Signature header on every webhook POST. See the webhooks reference for the verification pattern.

// Section 05 · Security practices

Recommended patterns.

• Never embed live keys in client-side code. Frontend JavaScript is public. Use a backend proxy that holds the live key and calls Crawlux on behalf of authenticated frontend users.
• Separate keys per environment. Different keys for dev, staging and production. Compromise of one environment does not require rotation of the others.
• Restrict by IP if possible. Team tier accounts can configure IP allowlists per key from the dashboard. Restrict production keys to your production egress IPs.
• Audit key usage. The dashboard shows last-used timestamp per key. Keys with last-used over 90 days ago are candidates for revocation.

// Related docs

Where to go from here.

• REST API reference — full endpoint surface
• Rate limits — per-tier quotas
• Webhooks reference — signature verification details