Proxy Setup

When you need to hide your API key from client-side code or route requests through your backend, use the baseUrl option to point to your proxy server.

Why Use a Proxy?

We strongly recommend using a proxy server for production deployments. Key benefits:

API Key Protection: Keep your Sarvam API key secure on your server instead of exposing it in client-side code where it can be easily extracted
Access Control: Enforce your own authentication (e.g., only logged-in users can start conversations)
Rate Limiting: Implement custom rate limits per user to prevent abuse
Usage Tracking: Log and monitor API usage per user for billing or analytics
Request Validation: Validate and sanitize requests before forwarding to Sarvam

Recommended Architecture

┌─────────────┐      JWT Auth      ┌──────────────┐    API Key     ┌─────────────┐
│   Client    │ ──────────────────▶│ Your Proxy   │ ──────────────▶│   Sarvam    │
│    App      │                    │   Server     │                │   API       │
└─────────────┘                    └──────────────┘                └─────────────┘

Use JWT-based authentication between your client and proxy—the same auth mechanism you use for the rest of your application. This ensures:

Only authenticated users can access the conversational AI
You can tie conversations to specific user accounts
No additional auth system to maintain

Server Setup (Python / FastAPI)

import os
import httpx
from fastapi import FastAPI, Request, Response, Depends, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import jwt

app = FastAPI()
security = HTTPBearer()

SARVAM_API_KEY = os.environ["SARVAM_API_KEY"]
JWT_SECRET = os.environ["JWT_SECRET"]
SARVAM_BASE = "https://apps.sarvam.ai/api/app-runtime/"

def verify_jwt(credentials: HTTPAuthorizationCredentials = Depends(security)):
    try:
        payload = jwt.decode(credentials.credentials, JWT_SECRET, algorithms=["HS256"])
        return payload
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")

@app.api_route("/api/sarvam/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(path: str, request: Request, user: dict = Depends(verify_jwt)):
    async with httpx.AsyncClient() as client:
        resp = await client.request(
            method=request.method,
            url=f"{SARVAM_BASE}{path}",
            headers={"Authorization": f"Bearer {SARVAM_API_KEY}"},
            content=await request.body(),
        )
        return Response(content=resp.content, status_code=resp.status_code, headers=dict(resp.headers))

Client Setup

How you pass authentication credentials to your proxy depends on your platform and deployment scenario.

Web (Same Domain)

When your proxy server and frontend are on the same domain, cookies are sent automatically with requests:

import { ConversationAgent } from "sarvam-conv-ai-sdk/browser";

const agent = new ConversationAgent({
  apiKey: "", // Empty - proxy handles Sarvam auth
  baseUrl: "/api/sarvam/", // Same-origin request
  config: {
    // ... your config
  },
});

Web (Cross-Domain) and React Native

For cross-domain requests, React Native, or any scenario where cookies aren’t automatically included, use customHeaders to pass authentication tokens:

const agent = new ConversationAgent({
  apiKey: "", // Empty - proxy handles Sarvam auth
  baseUrl: "https://api.yourapp.com/sarvam/",
  customHeaders: {
    Authorization: "Bearer eyJhbGciOiJIUzI1NiIs...",
    "X-User-Id": "user-123",
    "X-Session-Id": "session-456",
  },
  config: {
    // ... your config
  },
});

The SDK includes these headers in all HTTP requests to the API (e.g., when fetching the signed WebSocket URL).

Flutter

import 'package:sarvamconv_ai_sdk/sarvamconv_ai_sdk.dart';

final config = InteractionConfig(
  orgId: 'your_org_id',
  workspaceId: 'your_workspace_id',
  appId: 'your_app_id',
  userIdentifier: 'user@example.com',
  userIdentifierType: UserIdentifierType.email,
  interactionType: InteractionType.call,
  sampleRate: 16000,
);

// No API key passed - proxy server will add it
final agent = SamvaadAgent(
  config: config,
  baseUrl: 'https://your-proxy-server.com/sarvam-proxy/',
  headers: {
    'Authorization': 'Bearer user_session_token', // Your app's auth
  },
  audioInterface: DefaultAudioInterface(),
);

await agent.start();

Summary

Scenario	Authentication Method
Browser (same domain)	Cookies sent automatically
Browser (cross-domain)	Use `customHeaders`
React Native	Use `customHeaders`
Flutter	Use `headers`

Security Best Practices

Always Authenticate Users

app.use('/sarvam-proxy', async (req, res, next) => {
  const token = req.headers['authorization']?.replace('Bearer ', '');
  
  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }
  
  const user = await verifyUserToken(token);
  if (!user) {
    return res.status(401).json({ error: 'Invalid token' });
  }
  
  req.user = user;
  next();
});

Rate Limiting

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 60, // 60 requests per minute per IP
  message: { error: 'Too many requests' },
});

app.use('/sarvam-proxy', limiter);

Request Validation

app.use('/sarvam-proxy', (req, res, next) => {
  const allowedPaths = ['/orgs/', '/workspaces/', '/apps/'];
  const isAllowed = allowedPaths.some(p => req.path.includes(p));
  
  if (!isAllowed) {
    return res.status(403).json({ error: 'Path not allowed' });
  }
  
  next();
});

Environment Variables

Store your API key securely:

# .env (never commit this file!)
SARVAM_API_KEY=sk_samvaad_your_actual_api_key

Conversational AI SDKs

Client SDKs

Why Use a Proxy?

Recommended Architecture

Server Setup (Python / FastAPI)

Client Setup

Web (Same Domain)

Web (Cross-Domain) and React Native

Flutter

Summary

Security Best Practices

Always Authenticate Users

Rate Limiting

Request Validation

Environment Variables

​Why Use a Proxy?

​Recommended Architecture

​Server Setup (Python / FastAPI)

​Client Setup

​Web (Same Domain)

​Web (Cross-Domain) and React Native

​Flutter

​Summary

​Security Best Practices

​Always Authenticate Users

​Rate Limiting

​Request Validation

​Environment Variables

Why Use a Proxy?

Recommended Architecture

Server Setup (Python / FastAPI)

Client Setup

Web (Same Domain)

Web (Cross-Domain) and React Native

Flutter

Summary

Security Best Practices

Always Authenticate Users

Rate Limiting

Request Validation

Environment Variables