Skip to main content

API Credentials

Exotel's APIs use HTTP Basic Authentication with three credentials: API Key, API Token, and Account SID. This guide covers where to find them, how to use them, and best practices for credential management.

Your Three Credentials​

CredentialPurposeExample Format
API KeyPublic identifier (username in Basic Auth)2b04c2XXXXXXXXXX
API TokenSecret key (password in Basic Auth)a1b2c3d4XXXXXXXX
Account SIDUnique account identifier (used in API URLs)exotel or custom identifier

Finding Your Credentials​

Via Dashboard​

  1. Log in to my.exotel.com
  2. Navigate to Settings in the left sidebar
  3. Click API Settings
  4. Your credentials are displayed on the API Credentials page:
    • API Key -- visible in full
    • API Token -- click "Show" to reveal
    • Account SID -- visible in full
warning

Only Admin users can view API credentials. If you have a Supervisor or Agent role, ask your account Admin for the credentials or request a role change.

Using Credentials in API Calls​

Exotel APIs use HTTP Basic Authentication. Include your API Key and API Token in every request.

cURL Format​

curl "https://<api_key>:<api_token>@api.exotel.com/v2/accounts/<account_sid>/calls"

Concrete example:

curl "https://2b04c2XXXXXXXXXX:a1b2c3d4XXXXXXXX@api.exotel.com/v2/accounts/exotel/calls"

Authorization Header Format​

Alternatively, use the Authorization header with Base64-encoded credentials:

curl "https://api.exotel.com/v2/accounts/<account_sid>/calls" \
  -H "Authorization: Basic $(echo -n '<api_key>:<api_token>' | base64)"

API Endpoint by Region​

RegionAPI Base URL
Singaporehttps://api.exotel.com/v2/accounts/<account_sid>/
India (Mumbai)https://api.in.exotel.com/v2/accounts/<account_sid>/
info

Use the correct API base URL for your account region. Requests to the wrong region will return authentication errors or unexpected results.

Testing Your Credentials​

Verify your credentials work by making a simple API call:

curl -v "https://<api_key>:<api_token>@api.exotel.com/v2/accounts/<account_sid>/calls?limit=1"
ResponseMeaning
HTTP 200Credentials are valid
HTTP 401Invalid API Key or Token
HTTP 403Account suspended or IP restricted
HTTP 404Incorrect Account SID or region

Using Credentials in Code​

Python​

import requests

API_KEY = "your_api_key"
API_TOKEN = "your_api_token"
ACCOUNT_SID = "your_account_sid"

url = f"https://api.exotel.com/v2/accounts/{ACCOUNT_SID}/calls"
response = requests.get(url, auth=(API_KEY, API_TOKEN))
print(response.json())

Node.js​

const axios = require('axios');

const API_KEY = 'your_api_key';
const API_TOKEN = 'your_api_token';
const ACCOUNT_SID = 'your_account_sid';

axios.get(`https://api.exotel.com/v2/accounts/${ACCOUNT_SID}/calls`, {
  auth: { username: API_KEY, password: API_TOKEN }
}).then(response => {
  console.log(response.data);
});

PHP​

$api_key = 'your_api_key';
$api_token = 'your_api_token';
$account_sid = 'your_account_sid';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.exotel.com/v2/accounts/{$account_sid}/calls");
curl_setopt($ch, CURLOPT_USERPWD, "{$api_key}:{$api_token}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

Regenerating Your API Token​

If your API Token is compromised or you need to rotate it:

  1. Go to Settings > API Settings in the dashboard
  2. Click Regenerate Token
  3. Confirm the regeneration
  4. Copy the new token immediately
  5. Update all applications and integrations with the new token
warning

Regenerating your API Token immediately invalidates the old token. All active integrations using the old token will fail with HTTP 401 errors. Plan token rotation during a maintenance window and update all services promptly.

Security Best Practices​

Storage​

DoDo Not
Store credentials in environment variablesHardcode credentials in source code
Use a secrets manager (AWS Secrets Manager, HashiCorp Vault)Commit credentials to version control (Git)
Encrypt credentials at restStore in plain-text configuration files
Use separate credentials for dev and productionShare one set of credentials across environments

Access Control​

PracticeDescription
Principle of least privilegeOnly share credentials with team members who need API access
IP allowlistingRestrict API access to known IP addresses (enterprise feature)
Regular rotationRotate API Token every 90 days
Audit accessReview who has access to credentials quarterly
Revoke on departureRegenerate tokens when team members with access leave

Environment Variables​

Store credentials as environment variables rather than in code:

# .env file (do NOT commit to Git)
EXOTEL_API_KEY=your_api_key
EXOTEL_API_TOKEN=your_api_token
EXOTEL_ACCOUNT_SID=your_account_sid
import os

API_KEY = os.environ['EXOTEL_API_KEY']
API_TOKEN = os.environ['EXOTEL_API_TOKEN']
ACCOUNT_SID = os.environ['EXOTEL_ACCOUNT_SID']
tip

Add .env to your .gitignore file to prevent accidentally committing credentials. Use a .env.example file with placeholder values as a template for team members.

API Rate Limits​

LimitDefaultNotes
Requests per minute200Per account, across all API endpoints
Concurrent connections50Maximum simultaneous connections

When you exceed the rate limit, the API returns HTTP 429 (Too Many Requests). Implement exponential backoff in your application to handle rate limiting gracefully.

For higher rate limits, contact your account manager.

Troubleshooting​

IssueCauseSolution
HTTP 401 UnauthorizedInvalid API Key or TokenVerify credentials in Dashboard > Settings > API
HTTP 403 ForbiddenIP not allowlisted or account suspendedCheck IP restrictions; contact support
HTTP 404 Not FoundWrong Account SID or region URLVerify Account SID; use correct regional base URL
HTTP 429 Too Many RequestsRate limit exceededImplement backoff; request limit increase
Credentials not visibleNot an Admin userAsk your account Admin for credentials

Next Steps​