Skip to main content

​
Overview

WhizoAI uses API key authentication for all requests. Your API keys are unique to your account and should be kept secure.

​
Getting Your API Key

  1. Sign up for a WhizoAI account at whizo.ai
  2. Navigate to your API Keys dashboard
  3. Click “Create New API Key”
  4. Name your key (e.g., “Production App”, “Development”)
  5. Copy the generated key securely
API keys are only shown once during creation. Store them securely and never expose them in client-side code.

​
Authentication Methods

​
Bearer Token Authentication

Include your API key in the Authorization header with the Bearer prefix: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.whizo.ai/v1/scrape

​
API Key Header (Alternative)

You can also use the X-API-Key header: 
curl -H "X-API-Key: YOUR_API_KEY" \
     https://api.whizo.ai/v1/scrape

​
API Key Management

​
Creating API Keys

1

Navigate to Dashboard

Go to your API Keys dashboard
2

Create New Key

Click “Create New API Key” and provide a descriptive name
3

Set Permissions

Configure permissions and rate limits (Pro/Enterprise plans)
4

Copy and Store

Copy the key immediately and store it securely

​
API Key Properties

Each API key has the following properties:
​
id
string
Unique identifier for the API key
​
name
string
User-defined name for the key
​
prefix
string
First 8 characters shown for identification (e.g., “whizo_12…”)
​
permissions
array
List of allowed operations (Enterprise feature)
​
rateLimit
object
Rate limiting configuration
​
lastUsed
string
ISO timestamp of last usage
​
createdAt
string
ISO timestamp of creation

​
Rotating API Keys

For security best practices, regularly rotate your API keys:
  1. Create a new API key
  2. Update your applications to use the new key
  3. Test to ensure everything works
  4. Revoke the old key

​
Security Best Practices

  • Never commit API keys to version control
  • Use environment variables in applications
  • Don’t expose keys in client-side code
  • Store keys in secure credential management systems
# .env file
WHIZO_API_KEY=your_api_key_here

# In your application
const apiKey = process.env.WHIZO_API_KEY;
For Enterprise plans, create keys with minimal required permissions:
  • Read-only keys for monitoring
  • Limited endpoint access
  • IP address restrictions
Regularly check your API key usage in the dashboard:
  • Monitor for unexpected usage patterns
  • Set up usage alerts
  • Review access logs

​
Rate Limiting

API keys are subject to rate limits based on your plan:

​
Rate Limits by Plan

Free Plan

  • 10 requests per hour
  • 100 requests per day
  • 1 concurrent request

Starter Plan

  • 50 requests per hour
  • 500 requests per day
  • 3 concurrent requests

Pro Plan

  • 200 requests per hour
  • 2,000 requests per day
  • 10 concurrent requests

Enterprise

  • Custom limits
  • Burst allowances
  • Priority processing

​
Rate Limit Headers

Responses include rate limit information in headers: 
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1705234567
X-RateLimit-Retry-After: 3600

​
Handling Rate Limits

When you exceed rate limits, you’ll receive a 429 Too Many Requests response: 
{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 3600 seconds.",
    "details": {
      "retryAfter": 3600,
      "limit": 50,
      "remaining": 0,
      "resetTime": "2024-01-15T11:00:00Z"
    }
  }
}
Implement exponential backoff in your applications: 
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('X-RateLimit-Retry-After')) || 60;
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

​
Error Responses

Common authentication errors:
Status CodeError CodeDescription
401unauthorizedMissing or invalid API key
401key_revokedAPI key has been revoked
401key_expiredAPI key has expired
403insufficient_permissionsKey lacks required permissions
429rate_limitedRate limit exceeded
{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "details": {
      "hint": "Check your API key in the dashboard"
    }
  }
}

​
Testing Authentication

Test your API key with a simple request: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.whizo.ai/v1/auth/validate

{
  "success": true,
  "data": {
    "valid": true,
    "keyId": "key_abc123",
    "plan": "pro",
    "rateLimit": {
      "requestsPerHour": 200,
      "remaining": 198
    }
  }
}

​
Webhooks Authentication

For webhook endpoints, WhizoAI signs requests with your webhook secret:
JavaScript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === `sha256=${expectedSignature}`;
}

​
Next Steps

Make Your First Request

Start using the API with our quick start guide

API Reference

Explore all available endpoints

Rate Limits

Learn about rate limiting and optimization

Security Guide

Best practices for API security