Authentication

Telephony.io uses Bearer token authentication to secure all API requests. Your API keys are available in your dashboard and should be kept confidential.

API Keys

We provide two types of API keys depending on your use case:

• Client-side Key (Publishable): Safe to use in browsers and mobile apps. This key has limited permissions and is used for client-side SDK initialization.
• Server-side Key (Secret): Should only be used in your backend services. This key has full access to your account and can perform all API operations.

Making Authenticated Requests

Include your API key in the Authorization header of every request using the Bearer authentication scheme:

Authorization: Bearer <YOUR_API_KEY>

Example Request

Here's an example using cURL:

curl https://www.telephony.io/api/account/balance \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

Example with JavaScript (Node.js)

const response = await fetch('https://www.telephony.io/api/account/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log('Balance:', data.balance);

Authentication Errors

If your authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Key Management Best Practices

• Store API keys in environment variables, not in your code
• Use different keys for development, staging, and production environments
• Rotate your keys periodically (we recommend every 90 days)
• Use the principle of least privilege - only use server-side keys when necessary
• Monitor your API usage dashboard for unexpected activity

Rate Limiting

Each API key is subject to rate limits to ensure platform stability. Default limits are:

• Client-side keys: 100 requests per minute
• Server-side keys: 1000 requests per minute

If you exceed these limits, you'll receive a 429 Too Many Requests response. Contact us if you need higher limits.