Add token_source examples

Add one example per token source type (literal, endpoint, sandbox,
custom, caching) that connects to a room, plus a shared common.h for the
logging delegate and connect/observe session loop. The sandbox example
reads its sandbox ID from the environment so no IDs are committed.

These build against a local install of the SDK's token source API branch
via -DLIVEKIT_LOCAL_SDK_DIR; see token_source/README.md.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: alan-george-lk

CMakeLists.txt

@@ -82,6 +82,7 @@ endfunction()
 include(ExampleDeps)
 
 add_subdirectory(basic_room)
+add_subdirectory(token_source)
 add_subdirectory(simple_room)
 add_subdirectory(simple_rpc)
 add_subdirectory(simple_data_stream)

token_source/CMakeLists.txt

@@ -0,0 +1,45 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# One executable per token source type. Each shares common.h for the logging
+# delegate and the connect/observe session loop.
+
+# Resolve the SDK lib directory so -llivekit_ffi is found at link time.
+get_filename_component(_lk_cmake_dir "${LiveKit_DIR}" DIRECTORY)  # .../lib/cmake
+get_filename_component(_lk_lib_dir  "${_lk_cmake_dir}" DIRECTORY) # .../lib
+
+set(_token_source_examples
+  token_source_literal   literal.cpp
+  token_source_endpoint  endpoint.cpp
+  token_source_sandbox   sandbox.cpp
+  token_source_custom    custom.cpp
+  token_source_caching   caching.cpp
+)
+
+list(LENGTH _token_source_examples _count)
+math(EXPR _last "${_count} - 1")
+foreach(_i RANGE 0 ${_last} 2)
+  list(GET _token_source_examples ${_i} _target)
+  math(EXPR _src_idx "${_i} + 1")
+  list(GET _token_source_examples ${_src_idx} _src)
+
+  add_executable(${_target} ${_src})
+  target_include_directories(${_target} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+  target_link_libraries(${_target} PRIVATE ${LIVEKIT_CORE_TARGET})
+  target_link_directories(${_target} PRIVATE "${_lk_lib_dir}")
+
+  livekit_copy_windows_runtime_dlls(${_target})
+endforeach()
+
+unset(_token_source_examples)

token_source/README.md

@@ -0,0 +1,105 @@
+# Token sources
+
+These examples show the different ways to obtain the credentials
+(**WebSocket URL** + **participant JWT**) the SDK needs to join a room. Each
+example builds its own executable, constructs a single kind of
+[`TokenSource`](https://github.com/livekit/client-sdk-cpp/blob/main/include/livekit/token_source.h),
+connects to a room, logs participant join/leave for a few seconds, then
+disconnects.
+
+> Token sources are for the **initial connection only**. Once connected, the
+> LiveKit server refreshes the session token internally — your token source is
+> not called again unless you connect again. See the SDK's
+> [authentication docs](https://github.com/livekit/client-sdk-cpp/blob/main/docs/authentication.md).
+
+## The types
+
+| Example | Type | When to use |
+|---|---|---|
+| `literal.cpp` | `LiteralTokenSource` | You already have a URL + JWT (minted out of band, e.g. `lk token create`). The SDK consumes them as-is. |
+| `endpoint.cpp` | `EndpointTokenSource` | Recommended for production. The SDK POSTs request options to your backend token endpoint, which returns the URL + a fresh JWT. API keys stay server-side. |
+| `sandbox.cpp` | `SandboxTokenSource` | Local development only. Uses LiveKit Cloud's sandbox token server. Not for production. |
+| `custom.cpp` | `CustomTokenSource` | You have an internal auth/token system. Plug in your own async callback that returns credentials. |
+| `caching.cpp` | `CachingTokenSource` | A decorator that adds JWT-aware caching around any configurable source (endpoint/sandbox/custom) to cut down on fetch calls. |
+
+`LiteralTokenSource` is *fixed* (no per-call options); the others are
+*configurable* and accept
+[`TokenRequestOptions`](https://github.com/livekit/client-sdk-cpp/blob/main/include/livekit/token_source.h)
+(room name, participant identity, agent dispatch, ...).
+
+## Configuration
+
+All inputs come from environment variables, so no secrets or sandbox IDs are
+committed to source.
+
+| Variable | Used by | Notes |
+|---|---|---|
+| `LIVEKIT_URL` | literal, custom | WebSocket URL, e.g. `ws://localhost:7880`. |
+| `LIVEKIT_TOKEN` | literal, custom | Participant JWT. |
+| `LIVEKIT_TOKEN_ENDPOINT` | endpoint, caching | Token endpoint URL. Default `http://127.0.0.1:3000/createToken`. |
+| `LIVEKIT_TOKEN_ENDPOINT_METHOD` | endpoint, caching | Optional HTTP method (default `POST`). |
+| `LIVEKIT_TOKEN_ENDPOINT_HEADERS` | endpoint, caching | Optional newline-separated `Name: Value` headers. |
+| `LIVEKIT_SANDBOX_ID` | sandbox | Required. Sandbox ID from LiveKit Cloud. |
+| `LIVEKIT_AGENT_NAME` | sandbox | Optional agent to dispatch into the room. |
+| `LIVEKIT_AGENT_METADATA` | sandbox | Optional metadata for the dispatched agent. |
+
+## Building
+
+The token source API is newer than the latest published SDK release, so build
+these examples against a **local SDK build** of the
+[`feature/token_source_api`](https://github.com/livekit/client-sdk-cpp/tree/feature/token_source_api)
+branch rather than a downloaded release.
+
+```bash
+# 1. Build and install the SDK from the feature branch.
+git clone https://github.com/livekit/client-sdk-cpp.git
+cd client-sdk-cpp
+git checkout feature/token_source_api
+git submodule update --init --recursive
+./build.sh release --bundle --prefix "$HOME/livekit-sdk-install"
+
+# 2. Configure the examples against that local install.
+cd /path/to/cpp-example-collection
+cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR="$HOME/livekit-sdk-install"
+cmake --build build
+```
+
+Once the token source API ships in a release, you can drop
+`-DLIVEKIT_LOCAL_SDK_DIR` and use the normal download flow (optionally pinning
+`-DLIVEKIT_SDK_VERSION`).
+
+## Running
+
+The built binaries live under `build/token_source/`:
+
+```bash
+# Literal: bring your own URL + token
+export LIVEKIT_URL=ws://localhost:7880
+export LIVEKIT_TOKEN=<participant-jwt>
+./build/token_source/token_source_literal
+
+# Endpoint / caching: point at your token endpoint
+export LIVEKIT_TOKEN_ENDPOINT=http://127.0.0.1:3000/createToken
+./build/token_source/token_source_endpoint
+./build/token_source/token_source_caching
+
+# Sandbox: development-only, ID from the environment
+export LIVEKIT_SANDBOX_ID=<your-sandbox-id>
+./build/token_source/token_source_sandbox
+
+# Custom: callback returns credentials (this example reads the env)
+export LIVEKIT_URL=ws://localhost:7880
+export LIVEKIT_TOKEN=<participant-jwt>
+./build/token_source/token_source_custom
+```
+
+Generate a development token with the
+[LiveKit CLI](https://docs.livekit.io/home/cli/cli-setup/) (a dev server started
+with `livekit-server --dev` uses `devkey` / `secret`):
+
+```bash
+export LIVEKIT_TOKEN=$(lk token create \
+  --api-key devkey --api-secret secret \
+  -i my-participant --join --room my-room \
+  --valid-for 24h --token-only)
+```

token_source/caching.cpp

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026 LiveKit, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Caching token source: a decorator that adds JWT-aware caching to any
+// configurable token source (endpoint, sandbox, or custom).
+//
+// Repeated fetches for the same request options reuse the cached token until it
+// nears expiry or a force-refresh is requested, cutting down calls to your
+// backend. This example wraps an EndpointTokenSource.
+//
+// Environment:
+//   LIVEKIT_TOKEN_ENDPOINT          Token endpoint URL
+//                                   (default http://127.0.0.1:3000/createToken)
+//   LIVEKIT_TOKEN_ENDPOINT_METHOD   Optional HTTP method (default POST)
+//   LIVEKIT_TOKEN_ENDPOINT_HEADERS  Optional newline-separated "Name: Value" headers
+
+#include <livekit/livekit.h>
+#include <livekit/token_source.h>
+
+#include <iostream>
+#include <string>
+#include <utility>
+
+#include "common.h"
+
+namespace {
+
+using namespace token_source_example;
+
+bool cachingTokenSourceConnect() {
+  std::string endpoint_url = getenvOrEmpty("LIVEKIT_TOKEN_ENDPOINT");
+  if (endpoint_url.empty()) {
+    endpoint_url = "http://127.0.0.1:3000/createToken";
+  }
+
+  std::cout << "Caching token source wrapping endpoint: " << endpoint_url << "\n";
+
+  // Build the inner source, then wrap it. CachingTokenSource::wrap takes
+  // ownership of the inner source via unique_ptr.
+  auto inner = livekit::EndpointTokenSource::fromUrl(endpoint_url, endpointOptionsFromEnv());
+  auto token_source = livekit::CachingTokenSource::wrap(std::move(inner));
+
+  livekit::TokenRequestOptions request_options;
+  request_options.participant_identity = "robot-a";
+
+  livekit::Room room;
+  ParticipantLogDelegate delegate;
+  room.setDelegate(&delegate);
+  if (!room.connect(*token_source, request_options, livekit::RoomOptions())) {
+    std::cerr << "Failed to connect to room\n";
+    return false;
+  }
+  std::cout << "Connected to room: " << room.roomInfo().name << " (caching token source)\n";
+
+  return runConnectedSession(room);
+}
+
+} // namespace
+
+int main() {
+  livekit::initialize(livekit::LogLevel::Info);
+  const bool ok = cachingTokenSourceConnect();
+  livekit::shutdown();
+  return ok ? 0 : 1;
+}