Concept

Authentication & API keys

Every request to the TelVox Connect REST API carries your API key as a Bearer token. Browser dialers (WebRTC agent seats) sign in a different way, with SIP credentials. This page covers both, and how to keep your key out of the wrong places.

API keys

We set up your account with you. After that you create and delete API keys yourself, in the dashboard under API keys. An API key is one token that starts with sk_live_ followed by 48 hex characters. It is shown once, when you create it. TelVox keeps only a one-way hash and the first 12 characters, so nobody can show it to you again. If you lose it, create a new key and delete the old one.

# Created in the dashboard under API keys.
# Shown once, when you create it, so copy it then.

TELVOX_API_KEY=sk_live_<48 hex characters>

Keys have no scopes: every key can do everything your account can. Use one key per service, so you can delete one without touching the rest. The dashboard lists each key's name, its first 12 characters and when it was last used.

Authorize a request

Send the key as a Bearer token in the Authorization header. Read it from an environment variable rather than hard-coding it. The samples read it from TELVOX_API_KEY.

Also send Accept: application/json on every request. Without it, a validation error comes back as a redirect instead of a JSON body.

curl -X POST https://connect.telvox.dev/api/calls \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "from": "+918045670100",
    "to": "+919876500199",
    "url": "https://your.app/voice/answer"
  }'

When a key is missing or wrong

Both cases return 401 with a short JSON body. A request with no Authorization header gets the first one. A key that is wrong or has been deleted gets the second.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"API key required. Pass it as: Authorization: Bearer sk_live_..."}

Rotating and deleting keys

Keys are independent, so you can rotate without downtime. Create a new key, deploy it, check in the dashboard that its Last used time updates, then delete the old key.

• Rotate on a schedule, and straight away if a key shows up in logs, a repo or a screen-share.
• Use separate keys for each environment and each service, so deleting one affects as little as possible.
• Deleting a key takes effect at once. Calls already in progress carry on, but the key stops working for new requests.

Browser dialers

A browser can't hold your API key, so it doesn't use one. A browser dialer runs as a WebRTC agent seat: it signs in with SIP-over-WSS credentials and uses TURN servers for strict networks. You get those details from the dashboard, or from GET /api/partner/trunks/{trunk}/connection on accounts with SIP trunking switched on. Fetch them on your server with your API key, then pass them to a browser SIP library such as JsSIP or SIP.js.

# On your server. Works for WebRTC (wss) trunks on accounts
# with SIP trunking switched on.
curl https://connect.telvox.dev/api/partner/trunks/42/connection \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -H "Accept: application/json"

# Returns wss_url, sip_domain, username, password,
# secret_available and ice_servers (TURN).

The seat password is a long-lived SIP secret, not a short-lived token. Anyone who has it can sign in as that seat, so only hand it to agents who are signed in to your app, and rotate the secret in the dashboard if it leaks. See SIP trunks for the full endpoint, and SIP & WebRTC for how seats and trunks fit together.

Next: Call-control markup · SIP & WebRTC