Introduction

API key rotation is one of those boring controls that becomes urgent the moment you need it. If you are running a realtime interview practice avatar, you usually have at least two separate trust boundaries: a browser-facing app that drives the interview experience, and a server-side component that creates sessions, provisions avatars, or talks to a voice stack. Any long-lived API key in that path is a liability. If it leaks, you want a clean way to revoke it without breaking active sessions, and you want a rotation process that does not require downtime.

This post walks through a practical rotation design for a Next.js frontend plus a FastAPI backend. By the end, you should have a clear pattern for issuing short-lived session tokens to the browser, keeping Protoface API keys on the server, rotating those keys safely, and rolling forward without interrupting an ongoing interview practice session.

Separate the browser from the privileged API

The most important design choice is also the simplest: the browser should never see your long-lived Protoface API key. The browser can hold an ephemeral session token that is scoped to one interview session, one user, and a short expiry. The backend holds the API key and uses it to create or manage avatar sessions through the REST API, or to call the Python SDK if that fits your service layout better.

This matters because realtime avatars are not a static asset problem. You are typically orchestrating a streaming session, a voice agent, and some amount of conversational state. If you expose the server credential to the client, rotation becomes much harder: you now have to coordinate every deployed frontend bundle, any cached copy, and every user session that might still be active.

A better shape looks like this:

1. Next.js authenticates the user with your app session.

2. Next.js calls FastAPI to request an interview session.

3. FastAPI uses the current Protoface API key to create or update the avatar session.

4. FastAPI returns a short-lived, app-specific token or session descriptor to Next.js.

5. The browser uses only that ephemeral token to connect to your own backend or to a controlled embed flow.

That keeps the key rotation problem entirely on the server side, where it belongs.

Model rotation as key versions, not a single secret

In practice, “rotate the key” should mean “accept two versions temporarily, then retire the old one.” If you swap a secret atomically and invalidate the previous value immediately, you will create avoidable failures for in-flight requests, retried jobs, and workers that cached configuration a few seconds too long.

A simple versioned approach is usually enough:

• current: the API key used for new requests.

• previous: the old key, accepted for a short overlap window.

• rotation deadline: the time after which the previous key is no longer accepted.

Your app should read the current key from environment or secret storage on each process start, and ideally refresh it without a restart if your deployment platform supports it. The important part is that request signing and request execution happen on the backend; the frontend only receives session-scoped data.

If you have background workers creating or extending interview sessions, give them the same configuration source as your API process. Otherwise you can rotate the web server successfully and leave a stale worker crashing a minute later.

FastAPI implementation: accept old and new keys during the overlap window

A pragmatic implementation is to keep the active Protoface key in secret storage and expose a small admin-only endpoint to move the rotation forward. The backend then uses a key resolver that can return the current key, and optionally the previous one while it drains. Exact Protoface request fields depend on the API surface you use, so keep the example focused on structure.

from fastapi import FastAPI, Header, HTTPException

return resp.json()

from fastapi import FastAPI, Header, HTTPException

return resp.json()

from fastapi import FastAPI, Header, HTTPException

return resp.json()

During rotation, the app can support both secrets by checking the primary key first, then retrying with the secondary key if the first attempt returns an authentication error. That pattern is especially useful if some traffic lands on instances that have not yet refreshed their environment variables.

async def call_protoface(payload: dict) -> dict:

raise HTTPException(status_code=503, detail="unable to authenticate with Protoface")

async def call_protoface(payload: dict) -> dict:

raise HTTPException(status_code=503, detail="unable to authenticate with Protoface")

async def call_protoface(payload: dict) -> dict:

raise HTTPException(status_code=503, detail="unable to authenticate with Protoface")

That retry logic is not glamorous, but it eliminates a common failure mode during rotation: one process instance is still holding the old key while another has moved on, and the user experiences a transient auth error exactly when their interview session starts.

Next.js: keep the client session short-lived and restart-safe

On the Next.js side, the job is not to manage the Protoface secret. The job is to request an application session from FastAPI and persist only what the client needs to continue the experience. In most cases that means a session ID, an expiry, and maybe a signed token for your own backend.

If the interview practice avatar is embedded in a web page, keep the token lifetime short enough that a leaked token is not very useful. Use refresh-on-demand from the server rather than extending the browser session indefinitely. That way, a key rotation on the backend does not affect already-issued browser tokens until they naturally expire.

async function startInterview() {

}

async function startInterview() {

}

async function startInterview() {

}

If you are using server components or route handlers in Next.js, the same principle applies: the server code can call FastAPI, but the client bundle should never contain the upstream API credential. Put differently, the rotation boundary is the backend, not your React tree.

Operational details that prevent bad rotations

There are a few failure modes worth planning for before you rotate in production:

• Long-lived workers: anything that caches environment variables at startup needs a reload path.

• Retries: if your request fails with 401 during the rotation window, retry once with the previous key before escalating.

• Clock skew: expiration logic for short-lived browser tokens should tolerate small drift.

• Observability: log which key version was used, but never the secret value itself.

• Rollback: keep the previous key valid long enough to roll back a bad deploy.

For realtime avatar sessions specifically, also consider what happens to already-established media flows. WebRTC and similar streaming transports are stateful once connected. An auth key rotation should affect new control-plane operations, not abruptly sever media that is already flowing unless that is explicitly your revocation policy. That distinction is why key overlap windows are so useful.

When the backend creates a session, make the session itself authoritative. If the browser reconnects, it should resume by session identity and your own app token, not by reaching back to the upstream API key.

Where Protoface fits in this pattern

This is exactly the sort of architecture Protoface is designed to sit behind. You keep the API key server-side, call the REST API from FastAPI to create and manage avatars or realtime sessions, and let the browser work only with app-scoped session state. The same backend pattern also plays well with the Python SDK if you prefer not to hand-roll HTTP calls. For implementation details, use the documentation and, if you want a concrete integration reference, the Python SDK repository or the realtime quickstart examples.

If your interview agent is built on a voice stack such as LiveKit, the same principle applies: the agent process holds the privileged credentials, and the frontend never does. That keeps rotation local to your backend services instead of turning it into a frontend rollout problem.

Conclusion

API key rotation is less about swapping a secret and more about designing for bounded trust. For a realtime interview practice avatar, the clean pattern is: keep the upstream API key in FastAPI, issue short-lived app tokens to Next.js, accept old and new keys during a defined overlap window, and make sure your workers can reload configuration without a restart.

If you implement that shape, rotation becomes routine instead of risky. You can revoke a leaked key, roll credentials on a schedule, and keep ongoing interview sessions stable. For field-level details and integration examples, start with docs.protoface.com.