Skip to main content

​
API Key Authentication

All Telepath API requests require authentication using an API key.

​
Getting Your API Key

  1. Log into Telepath Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Give your key a descriptive name (e.g., “Production”, “Testing”)
  5. Copy the key immediately (you won’t be able to see it again)
  6. Store it securely (see security best practices below)

​
Using Your API Key

Include your API key in every request using the Authorization header: 
Authorization: Bearer sk_live_abc123def456...

​
Example Request

curl -X GET https://api.telepathvoice.com/v1/trunks \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"

​
Python Example

import requests

API_KEY = "sk_live_abc123def456..."
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.telepathvoice.com/v1/trunks",
    headers=headers
)

​
JavaScript Example

const API_KEY = "sk_live_abc123def456...";

const response = await fetch("https://api.telepathvoice.com/v1/trunks", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }
});

const data = await response.json();

​
Security Best Practices

​
Never Hardcode Keys

❌ Bad: 
API_KEY = "sk_live_abc123def456..."
✅ Good: 
import os
API_KEY = os.environ["TELEPATH_API_KEY"]

​
Use Environment Variables

Store your API key in environment variables: 
# .env file (add to .gitignore)
TELEPATH_API_KEY=sk_live_abc123def456...
Load in your code: 
from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.getenv("TELEPATH_API_KEY")

​
Rotate Keys Regularly

  1. Create a new API key
  2. Update your applications to use the new key
  3. Verify all systems working
  4. Revoke the old key

​
Limit Key Scope

Create separate keys for different purposes:
  • Development: Limited permissions, lower rate limits
  • Testing: Read-only access
  • Production: Full permissions, high rate limits
  • Monitoring: Read-only for dashboards

​
Monitor Key Usage

In the dashboard, each API key shows:
  • Last used timestamp
  • Request count
  • Error count
  • Usage patterns
Set up alerts for unusual activity.

​
Revoke Compromised Keys

If a key is compromised:
  1. Immediately revoke it in the dashboard
  2. Rotate all API keys
  3. Audit recent API calls
  4. Update any applications using the key
  5. Consider rotating AI provider credentials

​
Error Handling

​
Authentication Errors

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or has been revoked"
  }
}
Status Code: 401 Unauthorized Causes:
  • Key is invalid or revoked
  • Key format is wrong
  • Key is missing from header
Solution: Verify API key is correct and hasn’t been revoked.

​
Missing Authentication

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authorization header is missing"
  }
}
Status Code: 401 Unauthorized Solution: Include Authorization header in your request.

​
Rate Limiting

API requests are rate limited to prevent abuse.

​
Rate Limit Headers

Every response includes rate limit information: 
X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 5999
X-RateLimit-Reset: 1614556800
Fields:
  • X-RateLimit-Limit: Max requests per minute
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets

​
Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit of 6000 requests per minute exceeded"
  }
}
Status Code: 429 Too Many Requests Solution: Wait until X-RateLimit-Reset before retrying.

​
Handling Rate Limits

import time
import requests

def make_request_with_backoff(url, headers):
    while True:
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            # Rate limited - wait and retry
            reset_time = int(response.headers['X-RateLimit-Reset'])
            wait_time = max(0, reset_time - time.time())

            print(f"Rate limited. Waiting {wait_time} seconds...")
            time.sleep(wait_time + 1)  # Add 1 second buffer
            continue

        return response

​
Best Practices

​
Always Use HTTPS

Only use HTTPS (secure) connections. Never use HTTP. 
# ✅ Correct
url = "https://api.telepathvoice.com/v1/trunks"

# ❌ Wrong
url = "http://api.telepathvoice.com/v1/trunks"

​
Implement Retry Logic

Network requests can fail. Implement exponential backoff: 
import asyncio

async def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            async with aiohttp.ClientSession() as session:
                async with session.get(url, headers=headers) as resp:
                    return await resp.json()
        except Exception as e:
            if attempt == max_retries - 1:
                raise

            wait_time = 2 ** attempt  # 1, 2, 4 seconds
            await asyncio.sleep(wait_time)

​
Log API Activity

Log important API calls for debugging: 
import logging

logger = logging.getLogger(__name__)

def api_call(method, endpoint, **kwargs):
    headers = kwargs.get('headers', {})

    logger.info(f"{method} {endpoint}")

    try:
        response = requests.request(method, endpoint, **kwargs)
        logger.info(f"Status: {response.status_code}")
        return response
    except Exception as e:
        logger.error(f"API error: {e}")
        raise

​
Set Timeouts

Always set request timeouts: 
# Set 30 second timeout
response = requests.get(
    url,
    headers=headers,
    timeout=30
)

​
Webhook Authentication

Webhooks also include authentication to verify they’re from Telepath. See Webhooks documentation for signature verification.

​
API Endpoint Base URLs

  • Production: https://api.telepathvoice.com/v1
  • Rate Limits: 6000 requests per minute

​
Support

For authentication issues:

​
See Also