Authentication

Teler uses API key authentication. Every request to the Teler API, whether direct HTTP, SDK-mediated, or via a Bridge recipe, must include your API key in the X-API-Key header.

Get an API key

1. Sign in to the Teler dashboard.
2. Navigate to API keys.
3. Create a key, copy it, and store it somewhere safe.

Send the key

Every request includes the key in the X-API-Key header.

cURL

curl https://api.frejun.ai/api/v1/voice/calls/initiate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TELER_API_KEY" \
  -d '{ ... }'

Python

from teler import Client

# The SDK attaches X-API-Key automatically.
client = Client(api_key=os.environ["TELER_API_KEY"])

Node

import { Client } from "@frejun/teler";

// The SDK attaches X-API-Key automatically.
const client = new Client(process.env.TELER_API_KEY!);

The SDK constructors throw a BadParametersException if the key is empty. A bad or revoked key produces a 403 Forbidden (detail: Invalid API Key.), which the SDKs surface as ForbiddenException. A missing X-API-Key header produces a 422 Unprocessable Entity (the required header is absent).

Key rotation

Each Teler account currently has a single API key, generated once at signup. There is no self-serve key-management API and no multi-key overlap, so there is no zero-downtime rotation. Treat the key as a secret.

If the key is leaked, regenerate it from the dashboard. Regenerating replaces the old key immediately — the old value stops working the moment the new one is issued. Because there is no overlap window, plan a brief coordinated cutover: update TELER_API_KEY across all your services at rotation time so traffic switches to the new key together.

Storage

Do	Don’t
Read from environment variables (TELER_API_KEY)	Hard-code keys in source
Store in your secrets manager (Vault, AWS Secrets Manager, Doppler, etc.)	Commit .env files to Git
Restrict who can read them in your CI/CD	Send keys in URLs (they get logged)
Rotate on staff offboarding	Reuse the same key for sandbox and production

Per-environment isolation

Because each account has exactly one key, environment isolation means using a separate Teler account per environment — and therefore a separate key. That way you can regenerate a leaked staging key without touching production:

Env	Teler account	Key variable
Local dev	Dev account	TELER_API_KEY (your laptop)
Staging	Staging account	TELER_API_KEY (staging secrets)
Production	Production account	TELER_API_KEY (prod secrets, locked down)

Failure modes

Symptom	Cause	Fix
403 Forbidden from any endpoint	Invalid or revoked API key	Verify X-API-Key header is present and correct
422 Unprocessable Entity	The X-API-Key header is missing entirely	Ensure the header is being sent (some proxies strip custom headers)
SDK BadParametersException at construct time	Empty string passed in	Confirm TELER_API_KEY env var is set

Next steps

Errors The full HTTP error catalog and SDK exception mapping.

Webhook signing A separate secret protects webhooks: verify it on every request.

SDK Client Constructor reference for both Python and Node SDKs.