Authentication

The TryVox API uses HTTP Basic authentication. Every credential is a pair:

• Auth ID — your account-scoped identifier, used as the username
• Auth Token — the secret, used as the password

The same pair is also embedded in the URL path of account-scoped endpoints (/v1/voice/accounts/{auth_id}/...), so the Auth ID appears twice on the wire — once in the Authorization header and once in the path. They must match.

Credential Format

Auth IDs and Auth Tokens are issued together when you create an API key in the TryVox Dashboard. The Auth Token is shown once at creation time — store it somewhere safe. If you lose it, rotate the key.

A single TryVox account can have multiple key pairs. Each pair is independently revocable.

Making Authenticated Requests

Pass the credentials as Basic auth. With curl, the easiest form is -u:

curl -u TJab12cd34:1f2e3d4c5b6a7988a1b2c3d4e5f60718 \
  https://api.tryvox.io/v1/voice/accounts/TJab12cd34/calls

curl will base64-encode the pair and send the standard header:

Authorization: Basic VEphYjEyY2QzNDoxZjJlM2Q0YzViNmE3OTg4YTFiMmMzZDRlNWY2MDcxOA==

If your HTTP client doesn't have a Basic auth helper, build the header yourself: base64 of auth_id:auth_token.

Example: Outbound Call

curl -X POST https://api.tryvox.io/v1/voice/accounts/TJab12cd34/calls \
  -u TJab12cd34:1f2e3d4c5b6a7988a1b2c3d4e5f60718 \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155556789",
    "answer_url": "https://your-app.com/answer"
  }'

The Auth ID in the URL path (TJab12cd34) and the Auth ID in the credentials (-u TJab12cd34:...) are the same value. A mismatch returns 403 FORBIDDEN.

Account-Scoped Endpoints

Voice, Numbers, and Caller ID endpoints all live under your account namespace:

https://api.tryvox.io/v1/voice/accounts/{auth_id}/...
https://api.tryvox.io/v1/account/{auth_id}/numbers/...
https://api.tryvox.io/v1/accounts/{auth_id}/verified-caller-ids/...

Always use the API key's Auth ID in the URL — not your dashboard user ID, and not your tenant ID. Resources (numbers, verified caller IDs, recordings) are owned by the Auth ID that created them. If you rotate to a fresh API key with a new Auth ID, those resources stay attached to the old Auth ID.

Tenant Header

For multi-tenant workspaces, some endpoints accept an optional X-Tenant-ID header to scope the operation:

curl https://api.tryvox.io/v1/verify/start \
  -u TJab12cd34:1f2e3d4c5b6a7988a1b2c3d4e5f60718 \
  -H "X-Tenant-ID: TJab12cd34" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "channel": "sms"}'

Endpoints that require it (e.g. Verify) document this explicitly. Endpoints that don't mention it ignore the header.

Security Best Practices

Keep Auth Tokens Secret

• Never commit Auth Tokens to version control
• Never expose them in client-side code (browser JS, mobile apps)
• Use environment variables or a secrets manager in your application
• Use HTTPS — always. Basic auth over plaintext HTTP is broken by design

Rotate Keys Regularly

To rotate without downtime:

1. Create a new API key in the dashboard (you'll get a new Auth ID and Auth Token)
2. Re-attach any resources you need (numbers, verified caller IDs) to the new Auth ID
3. Roll your application over to the new credentials
4. Delete the old key

Because resources are owned by the issuing Auth ID, a rotation is more involved than swapping tokens — plan for it.

Monitor Key Usage

The dashboard shows per-key request volume and error rates. Watch for:

• Unexpected traffic spikes
• Requests from unfamiliar IP addresses
• Sudden 401 / 403 increases

If you suspect a key is compromised, delete it immediately and rotate.

Testing Authentication

A quick GET against your account is enough to confirm credentials work:

curl -u TJab12cd34:1f2e3d4c5b6a7988a1b2c3d4e5f60718 \
  https://api.tryvox.io/v1/account/TJab12cd34/numbers

Success (200 OK):

{
  "data": [
    {
      "e164": "+919876543210",
      "country": "IN",
      "status": "active"
    }
  ]
}

Failure (401 UNAUTHORIZED): wrong Auth ID, wrong Auth Token, or malformed header.

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "invalid API credentials"
  }
}

Failure (403 FORBIDDEN): the credentials are valid but the Auth ID in the URL doesn't match the authenticated key, or the account is suspended.

{
  "error": {
    "code": "ACCOUNT_SUSPENDED",
    "message": "your account is suspended. Please contact support."
  }
}

Next Steps

• Make your first call
• Verify a caller ID — required before outbound calls work
• Understand error responses
• Set up webhooks