Skip to main content

Authentication

Authentication Method​

SpiderIQ uses Bearer Token authentication with a three-part credential format.

Format​

Authorization: Bearer <client_id>:<api_key>:<api_secret>

Example​

Authorization: Bearer <your_token>

Getting Your Credentials​

To obtain API credentials, contact us:

✉️

Request API Access

Email admin@spideriq.ai with your company name and use case

You'll receive three credentials:

Client ID

Format: cli_xxxxxxxxxxxxxxx

Your unique client identifier. This is public and can be shared.

Example: cli_upxjrhfj3dzqmyf3

API Key

Format: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API key (50 characters). Keep this secret.

Example: sk_a3f7e9c2b8d4f6e1a5c9b7d3e8f2a4c6b9e1d5f8a2c7b4e9

API Secret

Format: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API secret (55 characters). Keep this secret.

Example: secret_f4e7c9a2b8d6e1f5c3a9b7d4e8f2a6c1b9e5d7f3a8c2b4e9d1f6a3c8b5e7f2

warning

Important: Your credentials are shown only once during registration. Store them securely immediately!

Using Authentication​

cURL​

curl https://spideriq.ai/api/v1/jobs/list \
  -H "Authorization: Bearer <your_token>"

Python​

import requests

headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(
    "https://spideriq.ai/api/v1/jobs/list",
    headers=headers
)

JavaScript/Node.js​

const headers = {
  'Authorization': 'Bearer <your_token>'
};

const response = await fetch(
  'https://spideriq.ai/api/v1/jobs/list',
  { headers }
);

PHP​

$ch = curl_init('https://spideriq.ai/api/v1/jobs/list');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <your_token>'
]);
$response = curl_exec($ch);

Authentication Errors​

401 Unauthorized​

Cause: Missing or invalid credentials

{
  "detail": "Invalid authentication token format. Expected: client_id:api_key:api_secret"
}

Solutions:

  • Check your Authorization header format
  • Ensure all three parts (client_id, api_key, api_secret) are present
  • Verify no extra spaces or characters

403 Forbidden​

Cause: Client account is inactive

{
  "detail": "Client account is inactive"
}

Solution: Contact support to reactivate your account

Security Best Practices​

🛡️

Credential Storage

Never commit credentials to version control or hardcode them in your application.

SPIDERIQ_CLIENT_ID=<your_client_id>
SPIDERIQ_API_KEY=<your_api_key>
SPIDERIQ_API_SECRET=<your_api_secret>
import os

client_id = os.getenv('SPIDERIQ_CLIENT_ID')
api_key = os.getenv('SPIDERIQ_API_KEY')
api_secret = os.getenv('SPIDERIQ_API_SECRET')

auth_token = f"{client_id}:{api_key}:{api_secret}"
headers = {"Authorization": f"Bearer {auth_token}"}
const client_id = process.env.SPIDERIQ_CLIENT_ID;
const api_key = process.env.SPIDERIQ_API_KEY;
const api_secret = process.env.SPIDERIQ_API_SECRET;

const auth_token = `${client_id}:${api_key}:${api_secret}`;
const headers = {
  'Authorization': `Bearer ${auth_token}`
};

Secrets Manager​

For production, use a secrets manager:

  • AWS Secrets Manager
  • HashiCorp Vault
  • Azure Key Vault
  • Google Cloud Secret Manager

Rate Limiting​

All API endpoints are rate limited:

X-RateLimit-Limitinteger

Maximum requests per minute: 100

X-RateLimit-Remaininginteger

Requests remaining in current window

X-RateLimit-Resetinteger

Unix timestamp when rate limit resets

429 Too Many Requests​

{
  "detail": "Rate limit exceeded. Maximum 100 requests per minute."
}

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1698345678
Retry-After: 42

Solution: Wait for the time specified in Retry-After header before retrying.

Testing Your Authentication​

Use the system health endpoint to verify your credentials and API connectivity:

curl https://spideriq.ai/api/v1/system/health \
  -H "Authorization: Bearer <your_credentials>"

Success Response (200 OK):

{
  "status": "healthy",
  "database": "connected",
  "queue": "connected",
  "timestamp": "2025-10-27T23:45:00Z"
}

Next Steps​

🚀

Make Your First Request

Submit your first scraping job

💻

API Reference

Explore all available endpoints