Authentication | Svara Docs

Authenticate requests with Bearer tokens, understand key formats, and handle rate limits.

Bearer token authentication

All API requests must include your API key in the Authorization header as a Bearer token:

curl https://api.svarapi.io/v1/usage \
  -H "Authorization: Bearer sk_live_your_key_here"

Requests without a valid API key return a 401 Unauthorized error.

API key formats

Svara issues two types of keys per account:

| Prefix | Environment | Behavior | |---|---|---| | sk_test_ | Sandbox | Simulates delivery without sending real voice notes. Useful for development and testing. | | sk_live_ | Production | Sends actual voice notes to the target platform. Counts toward your usage quota. |

Both key types use the same endpoints. Switch between them by changing the key in your Authorization header.

Keeping your key secure

Store your API key in environment variables, never in source code.
Use a secrets manager (e.g., AWS Secrets Manager, Doppler, or Vercel environment variables) in production.
Rotate keys immediately if you suspect a leak. You can generate a new key from your dashboard without downtime.

// Good — read from environment
const apiKey = process.env.SVARA_API_KEY;

// Bad — hardcoded key
const apiKey = "sk_live_abc123"; // Never do this

Rate limit headers

Every API response includes headers that tell you how many requests you have remaining:

| Header | Description | |---|---| | X-RateLimit-Limit | Maximum requests allowed per minute for your plan | | X-RateLimit-Remaining | Requests remaining in the current window | | X-RateLimit-Reset | Unix timestamp when the rate limit window resets | | X-Usage-Limit | Total voice notes included in your monthly plan | | X-Usage-Remaining | Voice notes remaining for the current billing period |

When X-RateLimit-Remaining reaches 0, subsequent requests return 429 Too Many Requests until the window resets.

# Example response headers
HTTP/2 200
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1710422460
X-Usage-Limit: 2000
X-Usage-Remaining: 1847

Example: checking headers in code

const response = await fetch("https://api.svarapi.io/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SVARA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const remaining = response.headers.get("X-RateLimit-Remaining");
if (parseInt(remaining) < 10) {
  console.warn("Approaching rate limit — consider slowing down requests");
}

import requests

response = requests.post(
    "https://api.svarapi.io/v1/send",
    headers={"Authorization": f"Bearer {api_key}"},
    json=payload,
)

remaining = int(response.headers.get("X-RateLimit-Remaining", 0))
if remaining < 10:
    print("Warning: approaching rate limit")