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":"[email protected]","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

TruthVouch rate limits are enforced on a per-hour basis. Each tier has a maximum number of requests allowed per hour:

Tier	Requests/Hour
SMB	1,000
MidMarket	5,000
Enterprise	10,000

SMB Tier

Perfect for development and small production deployments:

• 1,000 requests per hour
• No billing
• Test keys (tv_test_...) and live keys (tv_live_...) available

MidMarket Tier

For growing production deployments:

• 5,000 requests per hour
• Monthly billing
• Live keys (tv_live_...) required

Enterprise Tier

For large organizations:

• 10,000 requests per hour
• Custom SLA negotiated
• Dedicated support
• Contact sales

Endpoint-Specific Rate Limits

In addition to tier-based limits, certain public endpoints have specific rate limits that override tier-based limits:

Endpoint	Limit
truth-score-public	60 requests/min
shadow-audit-public	5 requests/24h
eu-assessment-public	30 requests/min
geo-audit	20 requests/min
public_verify	10 requests/hour
claim_watch	5 requests/hour
playground-public	10 requests/hour
calendly-webhook	60 requests/min
auth-login	10 requests/min
auth-reset	3 requests/hour

These endpoint-specific limits apply to all tiers and may be more restrictive than your tier-based limit. For example, shadow-audit-public has a maximum of 5 requests per 24 hours regardless of your subscription tier.

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 hour
• X-RateLimit-Remaining — Requests remaining this hour
• 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.

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 →