API Keys & Authentication

Learn how to create, secure, and use API keys for authenticating requests and integrating Cleversearch into your stack.

Key Types

Secret API KeyServer

Server-side authentication for API requests

Usage: Use in backend services and server actions

Exposure: Never expose in client-side code

Publishable KeyClient

Limited access for client-side tracking

Usage: Use in browser integrations with restricted scope

Exposure: Safe for client-side use

Webhook SecretSecurity

Verifies webhook signatures

Usage: Validate webhook payloads on your server

Exposure: Store in secure environment variables

Authentication Examples

Bearer Token

Send your secret key in the Authorization header

curl https://api.cleversearch.ai/v1/analysis \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Environment Variables

Keep keys out of source control

# .env.local
CLEVERSEARCH_SECRET_KEY=YOUR_SECRET_KEY
CLEVERSEARCH_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

# Usage in server code
const apiKey = process.env.CLEVERSEARCH_SECRET_KEY;

Webhook Verification

Validate webhook signatures before processing

import { verifyWebhook } from "@/lib/webhooks";

const isValid = verifyWebhook({
  payload: requestBody,
  signature: req.headers["x-cleversearch-signature"],
  secret: process.env.CLEVERSEARCH_WEBHOOK_SECRET,
});

Key Permissions Matrix

Quick overview of what each key type can access.

Analysis APIs

Secret: Full access

Publishable: No access

Webhook: No access

Tracker & Injection

Secret: Full access

Publishable: Read-only metadata

Webhook: No access

Usage & Billing

Secret: Full access

Publishable: No access

Webhook: No access

Webhook Events

Secret: No access

Publishable: No access

Webhook: Signature verification

Environment Setup Guidance

Local Development

Store keys in .env.local and never commit to git.

Preview/Staging

Use dedicated keys with reduced scopes for testing.

Production

Use least-privilege keys and rotate on a schedule.

Security Best Practices

Rotate keys regularly

Rotate keys every 90 days or immediately after exposure.

Use least-privilege keys

Create keys scoped to only the resources they need.

Monitor usage

Track API usage and set alerts for unusual activity.

Rate Limiting Tips

Batch analysis requests when possible to reduce total calls
Cache results for unchanged URLs to avoid redundant analysis
Use backoff and retry with jitter for 429 responses

Key Rotation Checklist

Generate a new key in the dashboard
Update your environment variables
Deploy and verify new key works
Revoke the old key after validation

Common Authentication Errors

401 Unauthorized

Check that you are using the correct key and header format.

403 Forbidden

The key does not have permission for this endpoint.

Rate limit exceeded

Reduce request volume or contact support for higher limits.

Next Steps

Ready to connect your data and start optimizing? Follow the setup guides to complete your integration.

Install Tracker Script Content Injection Setup Troubleshooting Guide

Operational Key Management

Key management should be predictable, auditable, and automated where possible.

●Use separate keys by environment and system boundary.

●Rotate secrets on a fixed schedule and after personnel changes.

●Log key usage patterns to detect unusual request bursts.

●Pair webhook secret rotation with endpoint signature validation tests.

Execution Phases

Week 1: Foundation

Finish installation and validate data flow.

Output: Connected tracker, imported sitemap, baseline analysis report.

Week 2: Prioritization

Select high-impact pages and define task backlog.

Output: Prioritized optimization list with owners and due dates.

Week 3-4: Iteration

Ship updates and verify score + business impact.

Output: Before/after snapshots with measurable deltas.

Common Mistakes

●Starting automation before validating tracker and sitemap integrity.

●Treating overall score as the only KPI and ignoring category gaps.

●Rolling out broad template changes without controlled testing.

●Skipping documentation of changes, making results hard to attribute.

Success Metrics

Analyzed Coverage

>= 90% priority URLs analyzed monthly

Ensures optimization decisions are based on current data.

Score Movement

+8 to +15 points on target templates in 30-60 days

Validates that executed recommendations are improving quality.

Execution Velocity

At least 1 improvement cycle per week

Creates compounding gains from consistent iteration.

API Keys & Authentication

Learn how to create, secure, and use API keys for authenticating requests and integrating Cleversearch into your stack.

Key Types

Secret API KeyServer

Server-side authentication for API requests

Usage: Use in backend services and server actions

Exposure: Never expose in client-side code

Publishable KeyClient

Limited access for client-side tracking

Usage: Use in browser integrations with restricted scope

Exposure: Safe for client-side use

Webhook SecretSecurity

Verifies webhook signatures

Usage: Validate webhook payloads on your server

Exposure: Store in secure environment variables

Authentication Examples

Bearer Token

Send your secret key in the Authorization header

curl https://api.cleversearch.ai/v1/analysis \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Environment Variables

Keep keys out of source control

# .env.local
CLEVERSEARCH_SECRET_KEY=YOUR_SECRET_KEY
CLEVERSEARCH_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

# Usage in server code
const apiKey = process.env.CLEVERSEARCH_SECRET_KEY;

Webhook Verification

Validate webhook signatures before processing

import { verifyWebhook } from "@/lib/webhooks";

const isValid = verifyWebhook({
  payload: requestBody,
  signature: req.headers["x-cleversearch-signature"],
  secret: process.env.CLEVERSEARCH_WEBHOOK_SECRET,
});

Key Permissions Matrix

Quick overview of what each key type can access.

Analysis APIs

Secret: Full access

Publishable: No access

Webhook: No access

Tracker & Injection

Secret: Full access

Publishable: Read-only metadata

Webhook: No access

Usage & Billing

Secret: Full access

Publishable: No access

Webhook: No access

Webhook Events

Secret: No access

Publishable: No access

Webhook: Signature verification

Environment Setup Guidance

Local Development

Store keys in .env.local and never commit to git.

Preview/Staging

Use dedicated keys with reduced scopes for testing.

Production

Use least-privilege keys and rotate on a schedule.

Security Best Practices

Rotate keys regularly

Rotate keys every 90 days or immediately after exposure.

Use least-privilege keys

Create keys scoped to only the resources they need.

Monitor usage

Track API usage and set alerts for unusual activity.

Rate Limiting Tips

Batch analysis requests when possible to reduce total calls
Cache results for unchanged URLs to avoid redundant analysis
Use backoff and retry with jitter for 429 responses

Key Rotation Checklist

Generate a new key in the dashboard
Update your environment variables
Deploy and verify new key works
Revoke the old key after validation

Common Authentication Errors

401 Unauthorized

Check that you are using the correct key and header format.

403 Forbidden

The key does not have permission for this endpoint.

Rate limit exceeded

Reduce request volume or contact support for higher limits.

Next Steps

Ready to connect your data and start optimizing? Follow the setup guides to complete your integration.

Install Tracker Script Content Injection Setup Troubleshooting Guide

Operational Key Management

Key management should be predictable, auditable, and automated where possible.

●Use separate keys by environment and system boundary.

●Rotate secrets on a fixed schedule and after personnel changes.

●Log key usage patterns to detect unusual request bursts.

●Pair webhook secret rotation with endpoint signature validation tests.

Execution Phases

Week 1: Foundation

Finish installation and validate data flow.

Output: Connected tracker, imported sitemap, baseline analysis report.

Week 2: Prioritization

Select high-impact pages and define task backlog.

Output: Prioritized optimization list with owners and due dates.

Week 3-4: Iteration

Ship updates and verify score + business impact.

Output: Before/after snapshots with measurable deltas.

Common Mistakes

●Starting automation before validating tracker and sitemap integrity.

●Treating overall score as the only KPI and ignoring category gaps.

●Rolling out broad template changes without controlled testing.

●Skipping documentation of changes, making results hard to attribute.

Success Metrics

Analyzed Coverage

>= 90% priority URLs analyzed monthly

Ensures optimization decisions are based on current data.

Score Movement

+8 to +15 points on target templates in 30-60 days

Validates that executed recommendations are improving quality.

Execution Velocity

At least 1 improvement cycle per week

Creates compounding gains from consistent iteration.