From 67d6e79e0eabdc6d951812281643d9c32fca884b Mon Sep 17 00:00:00 2001 From: lukasIO Date: Fri, 31 Jul 2026 10:41:06 +0200 Subject: [PATCH 1/6] introduce DevelopmentTokenServer and deprecate SandboxTokenServer --- README.md | 17 ++++++++------- src/room/token-source/TokenSource.ts | 31 +++++++++++++++------------- 2 files changed, 26 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 06b90f5151..aeb897605a 100644 --- a/README.md +++ b/README.md @@ -336,7 +336,7 @@ room.connect(configurableResponse.serverUrl, configurableResponse.participantTok |Mechanism: | using pre-generated credentials | via a http request to a url | via fully custom logic | |-------------|--|--|--| |Fixed | [`TokenSource.literal`](#tokensourceliteral) | — | [`TokenSource.literal(async () => { /* ... */ })`](#tokensourceliteral) | -|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.sandboxTokenServer`](#tokensourceendpoint) | [`TokenSource.custom`](#tokensourcecustom) | +|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.developmentTokenServer`](#tokensourceendpoint) | [`TokenSource.custom`](#tokensourcecustom) | #### TokenSource.Literal A fixed token source which returns a static set of credentials or a computed set of credentials @@ -373,21 +373,22 @@ const endpoint2 = TokenSource.endpoint("http://example.com/credentials-endpoint" await endpoint2.fetch({ agentName: "agent to dispatch" }) // { serverUrl: "...", participantToken: "... token encoding agentName ..." } ``` -#### TokenSource.SandboxTokenServer +#### TokenSource.DevelopmentTokenServer A configurable token source which makes a request to a -[sandbox token server endpoint](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server), +// TODO fix the dashboard link +[development token server endpoint](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server), a LiveKit-hosted token generation mechanism. This token generation mechanism is inherently insecure and should only be used for prototyping; do NOT use in production. -One parameter is required - the sandbox id from the dashboard. This is the `token-server-xxxxxx` +One parameter is required - the development token server id id from the dashboard. This is the `token-server-xxxxxx` value in `https://token-server-xxxxxx.sandbox.livekit.io`. Example: ```ts -const sandbox = TokenSource.sandboxTokenServer("token-server-xxxxxx"); -await sandbox.fetch({ agentName: "agent to dispatch" }); // { serverUrl: "...", participantToken: "... token encoding agentName ..." } +const devTokenSource = TokenSource.developmentTokenServer("token-server-xxxxxx"); +await devTokenSource.fetch({ agentName: "agent to dispatch" }); // { serverUrl: "...", participantToken: "... token encoding agentName ..." } ``` #### TokenSource.Custom @@ -401,11 +402,11 @@ output token. If you'd rather implement a fixed version of this TokenSource, see Example: ```ts -const sandbox = TokenSource.custom(async (options) => { +const myTokenSource = TokenSource.custom(async (options) => { // generate token info via custom means here return { serverUrl: "...", participantToken: "... options encoded in here ..." }; }); -await sandbox.fetch({ agentName: "agent to dispatch" }); +await myTokenSource.fetch({ agentName: "agent to dispatch" }); ``` ### RPC diff --git a/src/room/token-source/TokenSource.ts b/src/room/token-source/TokenSource.ts index 071aac5faa..68badabcbf 100644 --- a/src/room/token-source/TokenSource.ts +++ b/src/room/token-source/TokenSource.ts @@ -213,29 +213,35 @@ class TokenSourceEndpoint extends TokenSourceCached { const body = await response.json(); return TokenSourceResponse.fromJson(body, { // NOTE: it could be possible that the response body could contain more fields than just - // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer) + // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer) ignoreUnknownFields: true, }); } } -export type SandboxTokenServerOptions = { +export type DevelopmentTokenServerOptions = { baseUrl?: string; }; - -class TokenSourceSandboxTokenServer extends TokenSourceEndpoint { - constructor(sandboxId: string, options: SandboxTokenServerOptions) { +class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint { + constructor(tokenServerId: string, options: DevelopmentTokenServerOptions) { const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options; + // TODO is there an alternative path (and header) already that we could use instead of the sandbox naming one? super(`${baseUrl}/api/v2/sandbox/connection-details`, { ...rest, headers: { - 'X-Sandbox-ID': sandboxId, + 'X-Sandbox-ID': tokenServerId, }, }); } } +/** @deprecated use {@link DevelopmentTokenServerOptions} instead */ +export type SandboxTokenServerOptions = DevelopmentTokenServerOptions; + +/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */ +class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {} + export { /** The return type of {@link TokenSource.literal} */ type TokenSourceLiteral, @@ -243,7 +249,6 @@ export { type TokenSourceCustom, /** The return type of {@link TokenSource.endpoint} */ type TokenSourceEndpoint, - /** The return type of {@link TokenSource.sandboxTokenServer} */ type TokenSourceSandboxTokenServer, decodeTokenPayload, areTokenSourceFetchOptionsEqual, @@ -276,15 +281,13 @@ export const TokenSource = { }, /** - * TokenSource.sandboxTokenServer queries a sandbox token server for credentials, - * which supports quick prototyping / getting started types of use cases. - * - * This token provider is INSECURE and should NOT be used in production. - * - * For more info: - * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server + * @deprecated Use {@link TokenSource.developmentTokenServer} instead */ sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) { return new TokenSourceSandboxTokenServer(sandboxId, options); }, + + developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) { + return new TokenSourceDevelopmentTokenServer(tokenServerId, options); + }, }; From 9ba6fbd4ba27d4e12cd42d5ceb55cc423e769e63 Mon Sep 17 00:00:00 2001 From: lukasIO Date: Fri, 31 Jul 2026 10:50:09 +0200 Subject: [PATCH 2/6] fix readme link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aeb897605a..c124e24dbd 100644 --- a/README.md +++ b/README.md @@ -336,7 +336,7 @@ room.connect(configurableResponse.serverUrl, configurableResponse.participantTok |Mechanism: | using pre-generated credentials | via a http request to a url | via fully custom logic | |-------------|--|--|--| |Fixed | [`TokenSource.literal`](#tokensourceliteral) | — | [`TokenSource.literal(async () => { /* ... */ })`](#tokensourceliteral) | -|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.developmentTokenServer`](#tokensourceendpoint) | [`TokenSource.custom`](#tokensourcecustom) | +|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.developmentTokenServer`](#tokensourcedevelopmenttokenserver) | [`TokenSource.custom`](#tokensourcecustom) | #### TokenSource.Literal A fixed token source which returns a static set of credentials or a computed set of credentials From 7b535cad531c7ddc63f5b93ed0a4708fd2b5247c Mon Sep 17 00:00:00 2001 From: lukasIO Date: Fri, 31 Jul 2026 10:50:35 +0200 Subject: [PATCH 3/6] Create goofy-rules-swim.md --- .changeset/goofy-rules-swim.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/goofy-rules-swim.md diff --git a/.changeset/goofy-rules-swim.md b/.changeset/goofy-rules-swim.md new file mode 100644 index 0000000000..b829fd5ca2 --- /dev/null +++ b/.changeset/goofy-rules-swim.md @@ -0,0 +1,5 @@ +--- +"livekit-client": minor +--- + +introduce DevelopmentTokenServer and deprecate SandboxTokenServer From 2efb92f770dd9224519388afa14171aef4aa38f3 Mon Sep 17 00:00:00 2001 From: lukasIO Date: Fri, 31 Jul 2026 10:52:28 +0200 Subject: [PATCH 4/6] typedoc --- src/room/token-source/TokenSource.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/room/token-source/TokenSource.ts b/src/room/token-source/TokenSource.ts index 68badabcbf..9ee63c5516 100644 --- a/src/room/token-source/TokenSource.ts +++ b/src/room/token-source/TokenSource.ts @@ -287,6 +287,15 @@ export const TokenSource = { return new TokenSourceSandboxTokenServer(sandboxId, options); }, + /** + * TokenSource.developmentTokenServer queries a development token server for credentials, + * which supports quick prototyping / getting started types of use cases. + * + * This token provider is INSECURE and should NOT be used in production. + * + * For more info: + * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server + */ developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) { return new TokenSourceDevelopmentTokenServer(tokenServerId, options); }, From 04441d299324a89a2293aafdca2ba4d9ef573b20 Mon Sep 17 00:00:00 2001 From: lukasIO Date: Fri, 31 Jul 2026 10:55:34 +0200 Subject: [PATCH 5/6] export new type --- src/room/token-source/TokenSource.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/room/token-source/TokenSource.ts b/src/room/token-source/TokenSource.ts index 9ee63c5516..305ed687c4 100644 --- a/src/room/token-source/TokenSource.ts +++ b/src/room/token-source/TokenSource.ts @@ -250,6 +250,8 @@ export { /** The return type of {@link TokenSource.endpoint} */ type TokenSourceEndpoint, type TokenSourceSandboxTokenServer, + /** The return type of {@link TokenSource.developmentTokenServer} */ + type TokenSourceDevelopmentTokenServer, decodeTokenPayload, areTokenSourceFetchOptionsEqual, }; From 107b0dcab93f1fb42c4c9ba6c0bbca8f9322ef2e Mon Sep 17 00:00:00 2001 From: lukasIO Date: Fri, 31 Jul 2026 14:36:46 +0200 Subject: [PATCH 6/6] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c124e24dbd..86368086e7 100644 --- a/README.md +++ b/README.md @@ -382,7 +382,7 @@ a LiveKit-hosted token generation mechanism. This token generation mechanism is inherently insecure and should only be used for prototyping; do NOT use in production. -One parameter is required - the development token server id id from the dashboard. This is the `token-server-xxxxxx` +One parameter is required - the development token server id from the dashboard. This is the `token-server-xxxxxx` value in `https://token-server-xxxxxx.sandbox.livekit.io`. Example: