Authentication

All requests to the Scraper API require authentication using your unique API key. This page explains how to obtain and use your key securely.

Getting Your API Key

1. Log in to your Evomi Dashboard
2. Navigate to Settings → API
3. Copy your API key

Authentication Methods

The API accepts your key in three ways, checked in this priority order:

1. Query Parameter (Simplest)

Include the key in the URL as api_key:

curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://example.com&api_key=YOUR_API_KEY"

This method works directly in browser address bars, making it perfect for quick tests and simple integrations.

2. Header (Recommended for Production)

Pass the key in the x-api-key header:

curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://example.com" \
  -H "x-api-key: YOUR_API_KEY"

This is the most secure method and recommended for production use.

3. JSON Body (POST Requests)

For POST requests, include the key in the JSON payload:

curl -X POST "https://scrape.evomi.com/api/v1/scraper/realtime" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com"
  }'

Authentication Errors

Invalid or Missing Key (401)

{
  "success": false,
  "error": "Invalid API key",
  "timestamp": "2025-10-29T12:00:00Z"
}

Solution: Verify your API key in the dashboard and ensure it’s correctly passed in the request.

Insufficient Credits (402)

{
  "success": false,
  "error": "Insufficient credits",
  "credits_remaining": 0.5,
  "timestamp": "2025-10-29T12:00:00Z"
}

Solution: Add credits to your account through the dashboard.

Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code:

Python:

import os
api_key = os.environ.get('EVOMI_API_KEY')

Node.js:

const apiKey = process.env.EVOMI_API_KEY;

Bash:

export EVOMI_API_KEY="your_key_here"
curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://example.com&api_key=$EVOMI_API_KEY"

Use HTTPS Only

All requests must use HTTPS to encrypt your API key in transit. HTTP requests will be rejected.

Rotate Keys Regularly

If you suspect your key has been compromised:

1. Generate a new key in the dashboard
2. Update your applications with the new key
3. Revoke the old key

Use Different Keys for Different Environments

Consider using separate API keys for:

• Development/testing
• Staging
• Production

This allows you to track usage per environment and quickly revoke access if needed.

Rate Limiting

Your API key is associated with a concurrency limit that controls how many simultaneous requests you can make. The limit depends on your plan.

Check your remaining capacity in response headers:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3

See the Rate Limits page for detailed information on managing concurrent requests.

Testing Authentication

Verify your API key is working correctly:

curl "https://scrape.evomi.com/api/v1/scraper/health?api_key=YOUR_API_KEY"

Success Response:

{
  "success": true
}