Authentication & Rate Limits

All TruthVouch API endpoints (except Trust API) require authentication and are subject to rate limits based on your subscription tier.

Authentication Methods

1. Bearer Token (Recommended for SDKs)

Include your API key in the Authorization header:

curl -H "Authorization: Bearer tv_live_7e9c4a2b8f1d5c3a9e7b2f4d6c1a8e3b" \
  https://api.truthvouch.com/api/v1/alerts

2. X-API-Key Header

Alternatively, use the X-API-Key header:

curl -H "X-API-Key: tv_live_7e9c4a2b8f1d5c3a9e7b2f4d6c1a8e3b" \
  https://api.truthvouch.com/api/v1/alerts

3. JWT Token

Use a JWT token obtained via /api/v1/auth/login:

curl -X POST https://api.truthvouch.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"grantType":"password","email":"user@company.com","password":"password"}'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_...",
  "expiresIn": 3600
}

Use the access token:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.truthvouch.com/api/v1/alerts

Full JWT Documentation →

Rate Limits by Tier

Tier	Requests/Min	Concurrent	Burst	Storage
Sandbox	60	5	100	1GB
Professional	1,000	25	2,000	100GB
Enterprise	Custom	Custom	Custom	Custom

Sandbox Tier

Perfect for development and testing:

• 60 requests per minute
• 5 concurrent requests
• 100 requests burst capacity
• 1GB storage
• No billing
• Test keys (tv_test_...) only

Professional Tier

For production deployments:

• 1,000 requests per minute
• 25 concurrent connections
• 2,000 requests burst capacity
• 100GB storage
• Monthly billing
• Live keys (tv_live_...) required

Enterprise Tier

Custom limits for large organizations:

• Unlimited requests (custom SLA)
• Custom concurrency
• Dedicated infrastructure
• Unlimited storage
• Volume discounts available
• Contact sales

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1678886400

Meanings:

• X-RateLimit-Limit — Requests allowed per minute
• X-RateLimit-Remaining — Requests remaining this minute
• X-RateLimit-Reset — Unix timestamp when limit resets

Check remaining quota before making requests:

import requests

response = requests.get(
    "https://api.truthvouch.com/api/v1/alerts",
    headers={"Authorization": "Bearer tv_live_..."}
)

remaining = int(response.headers.get("X-RateLimit-Remaining", 0))
if remaining < 10:
    print(f"Warning: Only {remaining} requests remaining")

Handling Rate Limits

429 Too Many Requests

When you exceed rate limits, you receive a 429 response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "statusCode": 429,
    "requestId": "req_..."
  }
}

Response header:

Retry-After: 60

Exponential Backoff

Implement exponential backoff with jitter:

import time
import requests

def request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            wait_time = retry_after + random.uniform(0, 1)
            print(f"Rate limited, retrying in {wait_time:.1f}s")
            time.sleep(wait_time)
            continue

        return response

    raise Exception("Max retries exceeded")

SDKs handle this automatically — you don’t need to implement backoff yourself.

Burst Capacity

Rate limits include burst capacity for short traffic spikes:

• Sandbox: 60/min normally, burst to 100 for 10 seconds
• Professional: 1,000/min normally, burst to 2,000 for 10 seconds

After burst is exhausted, wait for the minute window to reset.

Key Management

Create Keys

1. Go to Settings → API Keys
2. Click Generate New Key
3. Select Live or Test
4. Copy immediately (not shown again)

Rotate Keys

For zero-downtime rotation:

1. Generate a new key
2. Update all services with the new key
3. Monitor logs to confirm new key is working
4. Delete the old key

Never hardcode keys — use environment variables or secret management.

Revoke Keys

To revoke a key:

1. Go to Settings → API Keys
2. Click Delete next to the key
3. Confirm deletion

Revocation is immediate — requests with the deleted key are rejected with 401 Unauthorized.

Tier Upgrade Path

As your usage grows, upgrade tiers:

1. Sandbox (development) → Professional (production)

   • No data migration needed
   • Keys remain valid
   • Rate limits increase immediately

2. Professional → Enterprise

   • Contact sales
   • Custom SLA negotiated
   • Dedicated support

Quota Tracking

Monitor your usage in the dashboard:

1. Settings → Billing → Usage
2. View requests this month, remaining quota, burst used
3. Set up billing alerts for overage warnings

Handling Quota Exceeded

If you hit quota limits:

1. Check your tier — Settings → Billing
2. Review usage — Settings → Billing → Usage
3. Optimize requests — Use batch APIs, cache results
4. Upgrade tier — Professional or Enterprise
5. Contact sales if you need higher limits

---

Next Steps

• API Keys →
• JWT Tokens →
• Error Handling →
• API Overview →