Authentication
The Influship API uses API key authentication for secure access. All requests (except /health) must include your API key in the X-API-Key header.
Getting Your API Key
Contact [email protected] to receive your API key.
Self-Serve Dashboard Coming Soon - Manage API keys, view usage statistics, and monitor rate limits directly from a web interface.
Using Your API Key
Include your API key in the X-API-Key header for all authenticated requests:
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.influship.com/v1/search
Authentication Errors
Invalid or Missing API Key (401)
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key",
"request_id": "req_7a8b9c0d1e2f3g4h"
}
}
- API key not provided in header
- Incorrect header name (must be
X-API-Key)
- Invalid or expired API key
- Extra whitespace in API key value
API Key Disabled - Payment Issues (403)
{
"error": {
"code": "payment_required",
"message": "API key disabled due to payment issues. Please update your payment method.",
"request_id": "req_7a8b9c0d1e2f3g4h"
}
}
IP Not Allowed (403)
{
"error": {
"code": "ip_not_allowed",
"message": "Request from unauthorized IP address",
"request_id": "req_7a8b9c0d1e2f3g4h"
}
}
Rate Limit Exceeded (429)
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Try again later.",
"details": {
"limit": 10000,
"remaining": 0,
"reset": 1640995200,
"retry_after": 3600
},
"request_id": "req_7a8b9c0d1e2f3g4h"
}
}
RateLimit-Limit: 10000
RateLimit-Remaining: 0
RateLimit-Reset: 1640995200
Retry-After: 3600
Rate Limiting
The API includes comprehensive rate limiting headers in all responses:
| Header | Description | Example |
|---|
RateLimit-Limit | Maximum requests allowed per hour | 10000 |
RateLimit-Remaining | Requests remaining in current hour | 9997 |
RateLimit-Reset | Unix timestamp when limit resets | 1640995200 |
Retry-After | Seconds to wait before retrying (429 only) | 3600 |
Check these headers proactively to avoid hitting rate limits. Implement exponential backoff when you receive 429 responses.
Security Best Practices
Environment Variables
Store API keys in environment variables, never in code
Never Commit Keys
Add .env files to .gitignore to prevent accidental commits
Separate Keys
Use different API keys for development and production
Rotate Regularly
Rotate keys periodically for enhanced security
Monitor Usage
Watch rate limit headers to avoid hitting limits
Implement Backoff
Use exponential backoff when receiving 429 responses
Example: Handling Authentication
JavaScript with Error Handling
async function makeAuthenticatedRequest(endpoint, options = {}) {
const apiKey = process.env.INFLUSHIP_API_KEY;
if (!apiKey) {
throw new Error('INFLUSHIP_API_KEY environment variable not set');
}
const response = await fetch(`https://api.influship.com${endpoint}`, {
...options,
headers: {
'X-API-Key': apiKey,
'Content-Type': 'application/json',
...options.headers
}
});
// Check for authentication errors
if (response.status === 401) {
throw new Error('Invalid API key. Check your credentials.');
}
if (response.status === 403) {
const error = await response.json();
throw new Error(`Access forbidden: ${error.error.message}`);
}
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After');
throw new Error(`Rate limited. Retry after ${retryAfter} seconds.`);
}
return response.json();
}
// Usage
try {
const results = await makeAuthenticatedRequest('/v1/search', {
method: 'POST',
body: JSON.stringify({ query: 'fitness influencers' })
});
console.log(results);
} catch (error) {
console.error('Request failed:', error.message);
}
Python with Retry Logic
import os
import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry
def create_session():
"""Create a requests session with retry logic"""
session = requests.Session()
# Configure retry strategy
retry_strategy = Retry(
total=3,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET", "POST"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)
return session
def make_authenticated_request(endpoint, method='GET', **kwargs):
"""Make an authenticated API request"""
api_key = os.environ.get('INFLUSHIP_API_KEY')
if not api_key:
raise ValueError('INFLUSHIP_API_KEY environment variable not set')
session = create_session()
url = f'https://api.influship.com{endpoint}'
headers = {
'X-API-Key': api_key,
'Content-Type': 'application/json'
}
response = session.request(method, url, headers=headers, **kwargs)
# Handle authentication errors
if response.status_code == 401:
raise Exception('Invalid API key. Check your credentials.')
if response.status_code == 403:
error = response.json()
raise Exception(f"Access forbidden: {error['error']['message']}")
response.raise_for_status()
return response.json()
# Usage
try:
results = make_authenticated_request(
'/v1/search',
method='POST',
json={'query': 'fitness influencers'}
)
print(results)
except Exception as e:
print(f'Request failed: {e}')
Monitoring Usage
Track your API usage through response headers:
function logRateLimitStatus(response) {
const limit = response.headers.get('RateLimit-Limit');
const remaining = response.headers.get('RateLimit-Remaining');
const reset = response.headers.get('RateLimit-Reset');
const usagePercent = ((limit - remaining) / limit * 100).toFixed(1);
const resetDate = new Date(reset * 1000);
console.log(`Rate Limit Status:
- Usage: ${usagePercent}% (${remaining}/${limit} remaining)
- Resets: ${resetDate.toLocaleString()}
`);
if (usagePercent > 80) {
console.warn('⚠️ Approaching rate limit!');
}
}
Next Steps
