Authentication

This guide explains how to authenticate with the API using API keys.

Obtaining an API Key

1. Log in to your Dashboard
2. Navigate to Settings > API Keys
3. Click "Create New API Key"
4. Configure your key settings:
   • Set a descriptive name for the key
   • Choose an expiration period (or select "No Expiry")
   • Set appropriate permissions

API Key Best Practices

Security

• Store API keys securely using environment variables
• Never commit API keys to version control
• Rotate keys regularly (recommended every 90 days)
• Use different keys for development and production

Permission Levels

API keys can have different permission levels:

1. Read-only

   • View datasets and scrapers
   • Access purchased dataset entries
   • View scraping results

2. Write

   • All read permissions
   • Create and modify scrapers
   • Create datasets
   • Update dataset entries

Using API Keys

Include your API key in requests using the x-api-key header:

GET https://scrapezy.com/api/datasets
x-api-key: your_api_key

Example successful response:

{
  "datasets": [
    {
      "id": "dataset_123",
      "name": "Example Dataset",
      "created_at": "2024-02-14T10:00:00Z"
    }
  ]
}

Response Codes

Here are the common authentication-related response codes:

Invalid API Key

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has expired"
  }
}

Insufficient Permissions

HTTP/1.1 403 Forbidden
Content-Type: application/json
 
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Your API key doesn't have permission to perform this action"
  }
}

Key Expiration

API keys can be set to expire after:

• 7 days
• 30 days
• 90 days
• 1 year
• Never (requires confirmation)

When a key expires, all requests will receive a 401 response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "This API key has expired. Please generate a new key.",
    "expiredAt": "2024-02-14T00:00:00Z"
  }
}

Best Practices

1. Security

   • Store API keys in environment variables
   • Never expose keys in client-side code
   • Rotate keys regularly
   • Use the principle of least privilege

2. Error Handling

   • Check response status codes
   • Handle rate limits gracefully
   • Implement proper retry logic
   • Log authentication errors

3. Key Management

   • Use descriptive key names
   • Set appropriate expiration dates
   • Revoke unused keys

Next Steps

• Basic Usage Guide
• Error Codes