Short-lived tokens - Finesse

Never ship an API key to a browser or a device. Your server mints a short-lived, single-use token with an API key that has the tts scope, and hands only the token over.

Mint a token on your server

const { token } = await client.tokens.create({ ttl_seconds: 60, voice_ids: [voiceId] });

Use it

const getToken = async () => (await (await fetch("/api/finesse-token")).json()).token;

// One-shot speech: sent as "Authorization: Bearer fin_tok_..."
const tts = new Finesse({ accessToken: await getToken() });
const audio = await tts.speech.create({ voice_id: voiceId, text: "Hi!" });

// Realtime: the token rides in the WebSocket subprotocol list. A token is spent by the
// handshake that uses it, so pass getAccessToken for reconnects to fetch a fresh one.
const live = new Finesse({ accessToken: await getToken() });
const rt = await live.realtime.connect({ getAccessToken: getToken });

In a browser, the TypeScript client runs without dangerouslyAllowBrowser when it holds a token.

How tokens behave

A token carries the tts scope only.
It works for one speech.create / speech.stream call, or one realtime session.
It dies when the key that minted it is revoked or expires.
A request refused before it runs (a 429 rate limit, a plan check) keeps its token, so you can retry with it.

Problem	Error	Code
The token is spent, expired or unknown	`AuthenticationError`	`token_invalid`
The voice is not in the token’s `voice_ids`	`PermissionDeniedError`	`voice_not_allowed`

The HTTP endpoint is Create an access token.