Introduction

Session token rotation is one of those infrastructure details that only gets noticed when it breaks. In a WebRTC voice or video agent, a “session token” usually sits between your backend and a browser or agent runtime, and it tends to be the thing that proves the client is still authorized to send or receive media. If you rotate it badly, you get dropped calls, failed renegotiations, duplicate sessions, or a reconnect loop that looks random from the outside.

For realtime avatar systems, the failure mode is worse because there are often two independent lifecycles to keep aligned: the transport session that carries audio/video, and the application session that controls the avatar, the agent state, and any per-user configuration. In this post we’ll build a practical mental model for rotating those tokens safely, then map that model onto a LiveKit-based voice agent and a web embed flow. By the end, you should be able to design rotation that preserves active sessions, limits blast radius, and avoids exposing long-lived credentials in the browser.

What “rotation” should mean in a realtime agent

Token rotation is not just “issue a new token before the old one expires.” In a realtime system, rotation needs to preserve these properties:

• Continuity: active media should keep flowing while a fresh credential is negotiated.

• Bounded trust: old tokens should stop working quickly, especially if they are browser-visible.

• Idempotency: retries during reconnect should not create duplicate sessions or race the old ones out of existence.

• Server authority: the backend, not the client, should decide when a token may be refreshed and what it may access.

In practice, that means you should distinguish between a long-lived API key used by your backend, and short-lived session credentials used by the browser or agent process. The API key stays private and can mint or manage sessions. The session token should be narrow in scope, short in lifetime, and refreshable without creating a new user-visible agent instance.

The basic rotation pattern

The safest pattern is a two-token overlap:

1. Issue a new token before the current one expires.

2. Deliver the new token over an authenticated control channel.

3. Have the client switch over when it is safe to do so.

4. Keep the old token valid for a short overlap window.

5. Revoke or let the old token expire once the new session is confirmed live.

That overlap matters. WebRTC sessions involve renegotiation, ICE restarts, reconnects after temporary network loss, and sometimes a full rejoin if the transport layer drops. If you revoke the old token too early, you can strand a healthy media pipeline while the client is still finishing its handoff.

A good rule is to treat session tokens like leases, not identities. The identity is the user, conversation, or agent thread. The token is just a temporary credential tied to that identity and a specific transport state.

Designing the backend for safe refresh

Your backend should own three jobs:

• mint session tokens with a short expiration;

• track the authoritative session record;

• accept refresh requests only from an already authenticated client or agent process.

That usually means the client never gets to ask for “any” token. It asks for a refresh for a specific session id, and the server validates that the requester still owns that session, that the session is not revoked, and that the request is within policy.

For browser-based clients, keep the API key out of the frontend entirely. Use a backend endpoint to mint a session token or an embed token, then hand the browser only the minimum it needs. If you need to allow refresh, issue a refreshable credential that is scoped to a single session and a short time window.

For agent runtimes, the same principle applies. The process that is generating audio or video should authenticate once, then refresh using a server-issued short-lived token rather than carrying a permanent secret in memory forever. If the runtime restarts, it should resume from the authoritative session state, not invent a new one.

Handling reconnects without duplicating sessions

In realtime voice and video, “token expired” and “network blipped” often look the same from the client side. If your client logic simply creates a fresh session every time it fails to reconnect, you will eventually produce duplicate avatars, duplicate assistant replies, or orphaned sessions that continue billing.

Instead, model reconnect as a state transition on the same logical session:

• connected — media is flowing normally.

• refreshing — new token requested, old token still valid.

• reconnecting — transport is being re-established with the new credential.

• confirmed — server acknowledges the same session is active again.

• failed — only now do you create a new session or surface an error.

Make the refresh path idempotent. If the browser asks twice because the first response was lost, the backend should return the same session state or at least a second valid token for the same session, not a second session object. This is the single easiest way to avoid “why do I hear two assistants talking at once?” incidents.

WebRTC-specific gotchas

There are a few transport-level details worth calling out:

• Token expiry does not instantly kill media. The client may continue streaming until it needs to renegotiate, reconnect, or authenticate a new control channel.

• ICE restarts can look like auth failures. Distinguish signaling/auth errors from transport path changes in your logs.

• Clock skew matters. If tokens are short-lived, a client with a skewed clock may think a token is still valid when the server rejects it.

• Grace periods help. A small overlap window is usually better than hard cutoff at the exact expiration second.

One practical implementation detail: the client should refresh proactively, not reactively. If your tokens live for 10 minutes, refresh at minute 8 or 9, not after the server has already rejected the request. That reduces the odds of a user-facing audio gap, especially on mobile or flaky Wi‑Fi.

Example: backend-issued refresh for a browser session

The exact request and response fields depend on your API design, but the shape is usually straightforward: a backend endpoint returns a short-lived session credential for one embed or one live conversation. A browser never sees your API key.

curl -X POST https://api.protoface.com/sessions \
}'

curl -X POST https://api.protoface.com/sessions \
}'

curl -X POST https://api.protoface.com/sessions \
}'

In your app, you would store the returned session identifier and refresh it before expiry. Keep the refresh endpoint behind your own authentication, and make it return a new short-lived credential for the same logical session.

Example: a LiveKit voice agent plugin integration

If you are attaching a talking face to a LiveKit voice agent, the token rotation problem usually sits at the boundary between the agent process and the avatar session. The agent may stay connected while the avatar transport needs a refreshed credential.

A simplified Python sketch looks like this:

from livekit.plugins import protoface

avatar.update_session_token(new_token)

from livekit.plugins import protoface

avatar.update_session_token(new_token)

from livekit.plugins import protoface

avatar.update_session_token(new_token)

The important bit is not the method names. It is the pattern: the agent keeps the same avatar identity, while the transport credential rotates underneath it. The plugin repo and examples are the right place to check the current integration details and supported refresh flow: https://github.com/protoface-ai.

If you are using a Pipecat-based stack, the same principle applies. The server-side pipeline should own refresh, and the media graph should survive token renewal without reconstructing the whole conversation state. The integration guide is here: https://docs.pipecat.ai/api-reference/server/services/video/protoface.

Where Protoface fits

Protoface is useful here because it cleanly separates backend-managed API access from short-lived session usage. The REST API and Python SDK are what you use to create and manage avatars and sessions from trusted server code, while customer-managed iframe embeds are designed so the browser never needs an API key at all. That architecture makes rotation much easier: your backend mints or refreshes a narrow session credential, and the client only gets what it needs for the current conversation.

For a browser embed, that matters even more because refresh has to coexist with parent-origin allowlists, per-embed voice and instructions, and rate limits. In other words, the session token is not a general-purpose auth artifact; it is part of the runtime contract for a single embedded avatar instance. If you are building on the REST API or Python SDK, keep your refresh logic in the backend and treat client-visible tokens as disposable.

If you want to see the available session and avatar operations, the docs are the place to start: https://docs.protoface.com.

Operational checklist

Before shipping, verify these behaviors in staging:

• Refresh happens before expiry with enough margin for network jitter.

• Old and new tokens overlap briefly, then the old one is revoked or expires naturally.

• Duplicate refresh requests return the same logical session, not a second session.

• Reconnect after a transient network drop resumes the same conversation state.

• Logs distinguish auth failure, signaling failure, and media-path failure.

• Browser clients never receive your long-lived API key.

Also test the ugly cases: refresh request timeout, server restart during overlap, token renewal while muted, renewal while speaking, and renewal after the client has been backgrounded for a few minutes. Realtime systems fail in the gaps between these cases.

Conclusion

Reliable session token rotation is mostly about discipline: keep the long-lived secret on the server, make session credentials short-lived and scoped, overlap old and new tokens briefly, and treat refresh as a state transition instead of a brand-new session. If you get those pieces right, your voice and video agents can survive reconnects and credential churn without dropping the conversation or duplicating the avatar.

If you are implementing this now, start with the docs, wire refresh into your backend first, and test the rotation path under real network conditions. Then apply the same pattern consistently across your WebRTC agent, browser embed, and server-side orchestration. The details vary, but the architecture does not.