Skip to main content

​
Authentication Flow

​
Authentication Methods

The primary auth method for dashboard users. How it works:
  1. User logs in with email/password via POST /auth/login
  2. Backend creates a JWT signed with HS256 algorithm using JWT_API_SECRET
  3. Token is set as an httpOnly cookie named access_token
  4. A refresh_token cookie is also set for token renewal
  5. All subsequent requests include the cookie automatically
Token contents: 
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "exp": 1739234400
}
The sub claim contains the user’s UUID, which is used to look up the full user record on each request.

​
2. API Key (Header-Based)

For server-to-server integrations and external API access. 
curl -X GET "https://api.vaani.ai/agents" \
  -H "x-api-key: vk_live_abc123def456"
See API Keys for details.

​
Login

curl -X POST "https://api.vaani.ai/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }' \
  -c cookies.txt

​
Signup

curl -X POST "https://api.vaani.ai/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "[email protected]",
    "password": "secure_password_123",
    "phone_number": "+16505551234"
  }'

​
Token Refresh

When the access token expires, the UI automatically calls the refresh endpoint: 
curl -X POST "https://api.vaani.ai/auth/refresh" \
  -H "Cookie: refresh_token=YOUR_REFRESH_TOKEN"
A new access_token cookie is set in the response.

​
Auth Chain

The JWT_API_SECRET must be identical across the backend and UI. A mismatch will cause all authenticated requests to fail with 401 errors.