Authentication & limits

API keys

Create keys in Dashboard → API keys. A key is shown once at creation and looks like sk-setu-…. Keys belong to a project, so usage and spend are tracked per project; you can create several (per app, per environment) and revoke any one without touching the others. Keys can also carry an expiry and their own per-minute rate limit.

Authorization: Bearer sk-setu-...

Every REST endpoint under https://platform.oogam.ai/v1 requires this header. For the realtime WebSocket, browsers cannot set headers — use a server-minted session_token instead of shipping your key to the page (details).

Keep keys server-side

• Never embed sk-setu-… in web or mobile app code.
• Rotate immediately if a key leaks — revoke in the dashboard, create a new one.
• Use separate keys for dev and production so a leaked test key never touches production limits.

What runs on every request

Each call passes the same gate, in order — knowing the order makes errors predictable:

1. Key check — 401 with missing_api_key (no header), invalid_api_key (bad format or unknown), revoked_api_key or expired_api_key; and 403 project_archived / account_suspended if the project or account is inactive. The Bearer scheme is case-insensitive.
2. Rate limit — requests per minute, per key (default 60/min). Over it: 429 rate_limit_exceeded with a Retry-After header (seconds). Back off and retry.
3. Product permission — each key carries a set of enabled products. A call to a product the key lacks returns 403 insufficient_permissions — see below.
4. Monthly spend limit — optional cap you set per project. Over it: 402 spend_limit_exceeded until the month rolls or you raise the cap.
5. Wallet balance — prepaid, in rupees. Empty: 402 insufficient_credits; top up in Dashboard → Billing.

Products & permissions

Every key is scoped to a set of products, so you can issue a voice-only key for one app and a broader key for another. Enable products per key in Dashboard → API keys.

• naad — the whole Voice API: audio endpoints, voices, realtime, and knowledge bases. naad-text-v1 and naad-embed-v1 are reachable with a naad key too.
• sutra — the Sutra chat models on /chat/completions.

A key calling a product it doesn't hold gets 403 insufficient_permissions. A product that isn't publicly available yet returns 403 api_not_available.

Billing model

Prepaid wallet, rupee-denominated, no lock-in: TTS bills per character, STT and realtime bill per audio minute. Current rates are returned live by GET /voices and shown in Dashboard → Billing. Failed jobs are not billed.

Good client behaviour

• Honour Retry-After on 429 — a simple sleep-and-retry loop is enough.
• Retry 502 upstream_error once; then surface it.
• Set generous HTTP timeouts for STT of long files (or use mode=async and poll).
• Log the code field from error responses — it is stable; messages may change.