Skip to main content
Telepath

Authentication

Authenticate your API requests using bearer tokens.

API Key Authentication

All Telepath API requests require authentication using an API key.

Getting Your API Key

  1. Log into the 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 in a secrets manager or environment variable

Using Your API Key

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

http 
Authorization: Bearer sk_live_abc123def456...

Example Request

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

Python Example

python 
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)
data = response.json()
print(data)

JavaScript Example

javascript 
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();
console.log(data);

Security Best Practices

Never Hardcode Keys

Avoid embedding API keys directly in source code:

python 
# Bad: hardcoded key in source code
API_KEY = "sk_live_abc123def456..."

# Good: read from environment variable
import os
API_KEY = os.environ["TELEPATH_API_KEY"]

Use Environment Variables

Store your API key in a .env file (never commit this file to version control):

bash 
# .env
TELEPATH_API_KEY=sk_live_abc123def456...
python 
from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.environ["TELEPATH_API_KEY"]

Rotate Keys Regularly

  1. Create a new API key in the Telepath Dashboard
  2. Update your application to use the new key
  3. Deploy the change and verify it works correctly
  4. Delete the old key from the Dashboard

Limit Key Scope

Use separate keys for different environments and purposes:

  • Dev: sk_test_dev_... — local development only
  • Testing: sk_test_ci_... — CI/CD pipelines
  • Production: sk_live_prod_... — live traffic only
  • Monitoring: sk_live_mon_... — read-only analytics access

Monitor Key Usage

Track usage patterns for each key in the Dashboard:

  • Last used: timestamp of most recent authenticated request
  • Request count: total requests in the current billing period
  • Error count: number of 4xx / 5xx responses associated with the key

Revoke Compromised Keys

  1. Immediately go to Settings → API Keys in the Dashboard
  2. Locate the compromised key
  3. Click Revoke
  4. Create a replacement key
  5. Audit recent activity logs for any unauthorized use

Error Handling

Authentication Errors

When authentication fails, the API returns a 401 Unauthorized response:

json 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "status": 401
  }
}

Common causes:

  • Typo or truncation in the key value
  • Using a test key against the production endpoint
  • The key has been revoked or expired

Solution: Verify the key in your Dashboard and ensure the Authorization header is formatted as Bearer <key>.

Missing Authentication

Requests sent without any Authorization header return a 401:

json 
{
  "error": {
    "code": "missing_authentication",
    "message": "No Authorization header provided",
    "status": 401
  }
}

Solution: Add the Authorization: Bearer <key> header to every API request.

Rate Limiting

Every API response includes rate limit headers:

http 
X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 5987
X-RateLimit-Reset: 1700000060

When you exceed the limit, the API returns a 429 Too Many Requests:

json 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 1700000060.",
    "status": 429,
    "retry_after": 1700000060
  }
}

Handle rate limits with exponential back-off:

python 
import time
import requests

def api_request_with_retry(url, headers, max_retries=3):
    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))
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Rate limit exceeded after max retries")

Best Practices

Always Use HTTPS

All API requests must use HTTPS. HTTP requests are rejected:

python 
# Correct
BASE_URL = "https://api.telepathvoice.com/v1"

# Never use HTTP — credentials would be sent in plaintext
# BASE_URL = "http://api.telepathvoice.com/v1"  # will be rejected

Implement Retry Logic

python 
import asyncio
import httpx

async def api_get(url: str, headers: dict, retries: int = 3) -> dict:
    async with httpx.AsyncClient() as client:
        for attempt in range(retries):
            try:
                r = await client.get(url, headers=headers, timeout=10)
                r.raise_for_status()
                return r.json()
            except httpx.HTTPStatusError as e:
                if e.response.status_code in (429, 500, 502, 503) and attempt < retries - 1:
                    await asyncio.sleep(2 ** attempt)
                    continue
                raise

Log API Activity

python 
import logging
import requests

logger = logging.getLogger(__name__)

def telepath_request(method, path, **kwargs):
    url = f"https://api.telepathvoice.com/v1{path}"
    response = requests.request(method, url, **kwargs)
    logger.info(
        "Telepath API %s %s → %d",
        method.upper(), path, response.status_code,
        extra={"request_id": response.headers.get("X-Request-Id")}
    )
    return response

Set Timeouts

Always configure request timeouts to avoid hanging connections:

python 
# Set connect + read timeouts
response = requests.get(url, headers=headers, timeout=(5, 30))

Webhook Authentication

Webhook payloads use a separate HMAC-SHA256 signature scheme. See the Webhooks documentation for signature verification details.

API Endpoint Base URLs

Production base URL https://api.telepathvoice.com/v1
Rate Limit requests/min 6,000 requests per minute per API key

Support & See Also