Authentication

How to authenticate your API requests

All API endpoints (except health and stats) require authentication using an API key.

Getting an API Key

1. Sign up at telco.dev
2. Go to your Dashboard
3. Click "Create API Key"
4. Copy and securely store your key

API keys follow the format: tk_live_ followed by 32 alphanumeric characters.

Authentication Methods

You can authenticate requests using any of these methods:

Option 1: Bearer Token (Recommended)

Pass your API key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer tk_live_your_key_here" \
  "https://api.telco.dev/v1/lookup/4155551234"

Option 2: X-API-Key Header

Pass your API key in the X-API-Key header:

curl -H "X-API-Key: tk_live_your_key_here" \
  "https://api.telco.dev/v1/lookup/4155551234"

Option 3: Query Parameter

Pass your API key as the apiKey query parameter:

curl "https://api.telco.dev/v1/lookup/4155551234?apiKey=tk_live_your_key_here"

Authentication Errors

Missing API Key

If no API key is provided, you'll receive a 401 Unauthorized response:

{
  "error": "unauthorized",
  "message": "API key required. Pass via X-API-Key header or api_key query param."
}

Invalid API Key

If the API key is invalid or inactive:

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

Public Endpoints

The following endpoints do not require authentication:

Security Best Practices

1. Never expose your API key in client-side code, public repositories, or logs
2. Use environment variables to store API keys in your applications
3. Rotate keys regularly if you suspect they may have been compromised
4. Use separate keys for development and production environments
5. Monitor usage in your dashboard to detect unusual activity

Example: Using Environment Variables

Node.js

// Load from environment variable
const apiKey = process.env.TELCO_API_KEY;

const response = await fetch(
  "https://api.telco.dev/v1/lookup/4155551234",
  {
    headers: {
      "Authorization": `Bearer ${apiKey}`
    }
  }
);

Python

import os
import requests

api_key = os.environ.get("TELCO_API_KEY")

response = requests.get(
    "https://api.telco.dev/v1/lookup/4155551234",
    headers={"Authorization": f"Bearer {api_key}"}
)

Managing API Keys

In your dashboard, you can:

• Create new keys with descriptive names
• View usage statistics for each key
• Deactivate keys that are no longer needed
• See last used timestamps for security monitoring