Skip to main content

​
Endpoint

POST /navai/realtime/client-secret
Creates an ephemeral client_secret token by calling OpenAI’s Realtime API. This token is used by frontend/mobile clients to establish secure WebSocket connections to OpenAI’s Realtime service.

​
Authentication

This endpoint requires an OpenAI API key, which can be provided in two ways:
  1. Server-side API key (recommended): Configure OPENAI_API_KEY environment variable
  2. Client-side API key: Pass apiKey in request body (only if allowApiKeyFromRequest is enabled)
The server-side API key always takes priority when both are present.

​
Request Headers

​
Content-Type
string
required
Must be application/json

​
Request Body

All fields are optional. If not provided, defaults from environment variables or backend configuration will be used.
​
model
string
OpenAI Realtime model name. Default: gpt-realtime
​
voice
string
Voice identifier for audio output. Default: marin
​
instructions
string
Base instructions for the AI assistant. Default: You are a helpful assistant.
​
language
string
Language for AI responses. When set, adds “Always reply in .” to instructions.
​
voiceAccent
string
Voice accent specification. When set, adds “Use a accent while speaking.” to instructions.
​
voiceTone
string
Voice tone specification. When set, adds “Use a tone while speaking.” to instructions.
​
apiKey
string
OpenAI API key from client. Only used if server-side key is not configured and allowApiKeyFromRequest is enabled.

​
Response

​
value
string
required
The ephemeral client secret token (starts with ek_)
​
expires_at
number
required
Unix timestamp (seconds) when the token expires

​
Example Request

curl -X POST http://localhost:3000/navai/realtime/client-secret \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-realtime",
    "voice": "marin",
    "instructions": "You are a helpful assistant.",
    "language": "Spanish",
    "voiceAccent": "neutral Latin American Spanish",
    "voiceTone": "friendly and professional"
  }'

​
Example Response

{
  "value": "ek_abc123def456...",
  "expires_at": 1730000000
}

​
Error Responses

​
500 - Missing API Key

{
  "error": "Missing API key. Configure openaiApiKey or send apiKey in request."
}
Occurs when no API key is available from either server configuration or request.

​
500 - API Key from Request Disabled

{
  "error": "Passing apiKey from request is disabled. Set allowApiKeyFromRequest=true to enable it."
}
Occurs when client sends apiKey in request but allowApiKeyFromRequest is false.

​
500 - Invalid TTL

{
  "error": "clientSecretTtlSeconds must be between 10 and 7200. Received: 9000"
}
Occurs when clientSecretTtlSeconds configuration is outside the valid range (10-7200 seconds).

​
500 - OpenAI API Error

{
  "error": "OpenAI client_secrets failed (401): Incorrect API key provided..."
}
Occurs when the OpenAI API request fails. The error message includes the HTTP status code and OpenAI’s error message.

​
Configuration

The endpoint behavior is controlled by NavaiVoiceBackendOptions passed to registerNavaiExpressRoutes:
  • openaiApiKey: Server-side OpenAI API key
  • defaultModel: Default model (default: gpt-realtime)
  • defaultVoice: Default voice (default: marin)
  • defaultInstructions: Default instructions
  • defaultLanguage: Default language
  • defaultVoiceAccent: Default voice accent
  • defaultVoiceTone: Default voice tone
  • clientSecretTtlSeconds: Token lifetime in seconds (10-7200, default: 600)
  • allowApiKeyFromRequest: Whether to accept API keys from requests (default: auto)

​
Environment Variables

  • OPENAI_API_KEY: Server-side API key
  • OPENAI_REALTIME_MODEL: Default model
  • OPENAI_REALTIME_VOICE: Default voice
  • OPENAI_REALTIME_INSTRUCTIONS: Default instructions
  • OPENAI_REALTIME_LANGUAGE: Default language
  • OPENAI_REALTIME_VOICE_ACCENT: Default voice accent
  • OPENAI_REALTIME_VOICE_TONE: Default voice tone
  • OPENAI_REALTIME_CLIENT_SECRET_TTL: Token TTL in seconds (default: 600)
  • NAVAI_ALLOW_FRONTEND_API_KEY: Whether to allow client API keys (true/false)

​
Security Notes

  • Server-side API key always takes priority over client-provided keys
  • If OPENAI_API_KEY is set, client keys are denied unless NAVAI_ALLOW_FRONTEND_API_KEY=true
  • If OPENAI_API_KEY is not set, client keys are allowed by default as a fallback
  • In production, always use server-side API keys and set NAVAI_ALLOW_FRONTEND_API_KEY=false

​
Implementation

Implemented in packages/voice-backend/src/index.ts:207-219 via createExpressClientSecretHandler.

Build docs developers (and LLMs) love

Get started for freeTalk to us