# Realtime API key hygiene

The Realtime API supports browser and mobile clients, but the project API key
must never leave your server. Verified against the Realtime docs on 2026-09-26.

## The contract

1. The browser calls YOUR backend endpoint (Express, FastAPI, Next.js route
   handler, anything server-side).
2. Your backend calls the OpenAI REST API with the project API key to create a
   Realtime session. The response includes an ephemeral client secret.
3. Your backend returns only the ephemeral secret to the browser.
4. The browser uses the ephemeral secret to connect directly to the Realtime API
   (WebRTC peer connection or websocket).

## Why ephemeral

- Ephemeral secrets are short-lived and scoped to one session. A leaked project
  key lets anyone burn your quota on any model; a leaked ephemeral secret dies
  in minutes and can only continue that session.
- The session-creation call is also where you set voice, instructions, and tool
  configuration, so the client cannot escalate its own permissions.

## Traps

- Do not cache ephemeral secrets across users. One secret per session, minted at
  session start.
- Do not log the project API key next to the ephemeral secret; keep the minting
  endpoint's logs free of both.
- Rate-limit the minting endpoint per user. Each mint is a billable-adjacent
  operation and an unauthenticated mint endpoint is a quota drain.

## Check before you ship

- Open devtools on the client: search the JS bundle and network tab for your
  project key pattern. It must appear nowhere.
- Confirm the ephemeral secret stops working after its expiry by replaying an
  old one.