Add token source API for fetching LiveKit tokens

.github/scripts/check_no_private_symbols.py

@@ -17,7 +17,7 @@
 Verify that liblivekit's exported ABI does not leak private dependency symbols.
 
 The LiveKit SDK statically links several private dependencies (spdlog, fmt,
-google::protobuf, absl).  When those symbols escape the dynamic symbol table
+google::protobuf, absl, nlohmann/json).  When those symbols escape the dynamic symbol table
 of liblivekit.{so,dylib,dll}, they collide at runtime with the same libraries
 loaded elsewhere in the host process (a common failure mode is ROS 2's
 rcl_logging_spdlog ABI-clashing with our vendored spdlog and crashing inside
@@ -52,6 +52,7 @@
     "fmt::v",
     "google::protobuf",
     "absl::",
+    "nlohmann::",
 ]
 
 MAX_REPORTED_LEAKS = 20

.github/workflows/builds.yml

@@ -114,6 +114,7 @@ jobs:
             libssl-dev \
             libprotobuf-dev protobuf-compiler \
             libabsl-dev \
+            libcurl4-openssl-dev \
             libwayland-dev libdecor-0-dev
 
       - name: Install deps (macOS)

.github/workflows/cpp-checks.yml

@@ -62,7 +62,7 @@ jobs:
           sudo apt-get install -y \
             build-essential cmake ninja-build pkg-config \
             llvm-dev libclang-dev clang \
-            libssl-dev wget ca-certificates gnupg
+            libssl-dev libcurl4-openssl-dev wget ca-certificates gnupg
 
       - name: Install clang-tidy 19 (for ExcludeHeaderFilterRegex support)
         run: |

.github/workflows/make-release.yml

@@ -116,6 +116,7 @@ jobs:
             libssl-dev \
             libprotobuf-dev protobuf-compiler \
             libabsl-dev \
+            libcurl4-openssl-dev \
             libwayland-dev libdecor-0-dev
 
       - name: Install deps (macOS)

.github/workflows/tests.yml

@@ -115,6 +115,7 @@ jobs:
             libssl-dev \
             libprotobuf-dev protobuf-compiler \
             libabsl-dev \
+            libcurl4-openssl-dev \
             libwayland-dev libdecor-0-dev \
             jq
 
@@ -208,7 +209,6 @@ jobs:
             --gtest_brief=1 `
             --gtest_output="xml:build-release\unit-test-results.xml"
 
-      # ---------- Start livekit-server for integration tests ----------
       - name: Start livekit-server
         if: matrix.e2e-testing
         id: livekit_server
@@ -248,12 +248,22 @@ jobs:
           fi
           lk --version
 
+      - name: Start token server
+        if: matrix.e2e-testing
+        id: token_server
+        uses: livekit/token-server-action@a1e42c649a1998d5b224f5102f252c07762024f0 # v0.0.1
+        with:
+          livekit-url: ws://localhost:7880
+          api-key: devkey
+          api-secret: secret
+
       - name: Run integration tests
         if: matrix.e2e-testing
         timeout-minutes: 10
         shell: bash
         env:
           RUST_LOG: "metrics=debug"
+          LIVEKIT_CREATE_TOKEN_URL: ${{ steps.token_server.outputs.token-url }}
         run: |
           set -euo pipefail
           source .token_helpers/set_data_track_test_tokens.bash
@@ -265,6 +275,11 @@ jobs:
         shell: bash
         run: tail -n 500 "${{ steps.livekit_server.outputs.log-path }}" || true
 
+      - name: Dump token server log on failure
+        if: failure() && matrix.e2e-testing && steps.token_server.outputs.log-path != ''
+        shell: bash
+        run: tail -n 200 "${{ steps.token_server.outputs.log-path }}" || true
+
       # ---------- Upload results ----------
       - name: Upload test results
         if: always()
@@ -329,6 +344,7 @@ jobs:
             libssl-dev \
             libprotobuf-dev protobuf-compiler \
             libabsl-dev \
+            libcurl4-openssl-dev \
             libwayland-dev libdecor-0-dev
           pip install --break-system-packages gcovr
 

AGENTS.md

@@ -77,7 +77,7 @@ Be sure to update the directory layout in this file if the directory layout chan
 | `examples/` | In-tree example applications |
 | `client-sdk-rust/` | Git submodule holding the Rust core of the SDK|
 | `client-sdk-rust/livekit-ffi/protocol/*.proto` | FFI contract (protobuf definitions, read-only reference) |
-| `cmake/` | Build helpers (`protobuf.cmake`, `spdlog.cmake`, `LiveKitConfig.cmake.in`) |
+| `cmake/` | Build helpers (`protobuf.cmake`, `spdlog.cmake`, `nlohmann_json.cmake`, `LiveKitConfig.cmake.in`) |
 | `docker/` | Dockerfile for CI and SDK distribution images |
 | `scripts/` | Developer / CI helper scripts (e.g. `clang-tidy.sh`) |
 | `docs/` | Documentation root. `docs/` holds hand-written long-form Markdown intended to also read well on GitHub. |
@@ -338,6 +338,7 @@ Adhere to clang-tidy checks configured in `.clang-tidy`. After C++ code changes,
 |------------|-------|-------|
 | protobuf | Private (built-in) | Vendored via FetchContent (Unix) or vcpkg (Windows) |
 | spdlog | **Private** | FetchContent or system package; must NOT leak into public API |
+| nlohmann/json | **Private** | Header-only; vendored via FetchContent (Unix) or vcpkg (Windows); must NOT leak into public API |
 | client-sdk-rust | Build-time | Git submodule, built via cargo during CMake build |
 | Google Test | Test only | FetchContent in `src/tests/CMakeLists.txt` |
 
@@ -356,7 +357,7 @@ Tests are under `src/tests/` using Google Test:
 cd build-debug && ctest
 ```
 
-Integration tests (`src/tests/integration/`) cover: room connections, callbacks, data tracks, RPC, logging, audio processing, and the subscription thread dispatcher.
+Integration tests (`src/tests/integration/`) cover: room connections, callbacks, data tracks, RPC, logging, audio processing, and the subscription thread dispatcher. The token source HTTP/JSON wire contract (request serialization, response parsing, header passthrough, GET support, sandbox URL/header resolution) is covered by mocked unit tests in `src/tests/unit/test_token_source.cpp`, which inject a stub HTTP transport so no live server is needed. For a full end-to-end check, `TokenSourceEndpointConnectTest` connects a `Room` with a real JWT minted by the `livekit/token-server-action` token server pointed at the local dev `livekit-server`. The action exposes its `/createToken` endpoint as a `token-url` output; `tests.yml` passes that to the integration test step as `LIVEKIT_CREATE_TOKEN_URL`, which the test reads to locate the endpoint. The server is started in the `e2e-testing` jobs via the token server's reusable GitHub Action, pinned by SHA in `tests.yml`.
 
 When adding new client facing functionality, add a new test case to the existing test suite.
 When adding new client facing functionality, add benchmarking to understand the limitations of the new functionality.
@@ -403,6 +404,13 @@ all filtered stages; normal pull requests and pushes use the path filters.
 - `.github/workflows/docker-validate.yml` — Docker image validation workflow,
   outside PR-review aggregation.
 
+The `tests.yml` e2e jobs consume two external, pinned composite actions:
+`livekit/dev-server-action` (local `livekit-server`) and
+`livekit/token-server-action` (a real `/createToken` endpoint used by
+`TokenSourceEndpointConnectTest`). Both are referenced by commit SHA. The token
+server action lives in its own repo on purpose — it is general-purpose like
+`dev-server-action` and is not bundled here.
+
 When adding or renaming files that affect a CI stage, update the matching
 `ci.yml` `changes` filter in the same PR. For example, new build scripts,
 CMake files, package manifests, or reusable build workflows should be added to

CMakeLists.txt

@@ -93,6 +93,8 @@ file(MAKE_DIRECTORY ${PROTO_BINARY_DIR})
 include(protobuf)
 # spdlog logging library (PRIVATE dependency).
 include(spdlog)
+# nlohmann/json header-only library (PRIVATE dependency).
+include(nlohmann_json)
 # Ensure protoc executable is found.
 if(TARGET protobuf::protoc)
   set(Protobuf_PROTOC_EXECUTABLE "$<TARGET_FILE:protobuf::protoc>")
@@ -392,6 +394,11 @@ add_library(livekit SHARED
   src/room_proto_converter.cpp
   src/room_proto_converter.h
   src/subscription_thread_dispatcher.cpp
+  src/token_source.cpp
+  src/token_source_http.cpp
+  src/token_source_json.cpp
+  src/token_source_jwt.cpp
+  src/token_source_internal.h
   src/local_participant.cpp
   src/remote_participant.cpp
   src/stats.cpp
@@ -457,10 +464,18 @@ target_include_directories(livekit SYSTEM PRIVATE
 target_link_libraries(livekit
   PRIVATE
     spdlog::spdlog
+    nlohmann_json::nlohmann_json
     livekit_ffi
     ${LIVEKIT_PROTOBUF_TARGET}
 )
 
+if(WIN32)
+  target_link_libraries(livekit PRIVATE winhttp)
+else()
+  find_package(CURL REQUIRED)
+  target_link_libraries(livekit PRIVATE CURL::libcurl)
+endif()
+
 target_compile_definitions(livekit
   PRIVATE
     SPDLOG_ACTIVE_LEVEL=${_SPDLOG_ACTIVE_LEVEL}

CMakePresets.json

@@ -94,8 +94,7 @@
       "cacheVariables": {
         "CMAKE_BUILD_TYPE": "Release",
         "LIVEKIT_BUILD_EXAMPLES": "ON",
-        "LIVEKIT_BUILD_TESTS": "OFF",
-        "VCPKG_MANIFEST_FEATURES": "examples"
+        "LIVEKIT_BUILD_TESTS": "OFF"
       }
     },
     {
@@ -107,8 +106,7 @@
       "cacheVariables": {
         "CMAKE_BUILD_TYPE": "Debug",
         "LIVEKIT_BUILD_EXAMPLES": "ON",
-        "LIVEKIT_BUILD_TESTS": "OFF",
-        "VCPKG_MANIFEST_FEATURES": "examples"
+        "LIVEKIT_BUILD_TESTS": "OFF"
       }
     },
     {
@@ -216,8 +214,7 @@
       "cacheVariables": {
         "CMAKE_BUILD_TYPE": "Release",
         "LIVEKIT_BUILD_EXAMPLES": "ON",
-        "LIVEKIT_BUILD_TESTS": "ON",
-        "VCPKG_MANIFEST_FEATURES": "examples"
+        "LIVEKIT_BUILD_TESTS": "ON"
       }
     },
     {
@@ -229,8 +226,7 @@
       "cacheVariables": {
         "CMAKE_BUILD_TYPE": "Debug",
         "LIVEKIT_BUILD_EXAMPLES": "ON",
-        "LIVEKIT_BUILD_TESTS": "ON",
-        "VCPKG_MANIFEST_FEATURES": "examples"
+        "LIVEKIT_BUILD_TESTS": "ON"
       }
     },
     {

README.md

@@ -21,7 +21,7 @@ Use this SDK to add realtime video, audio and data features to your C++ app. By
 
 - [LiveKit docs](https://docs.livekit.io)
 - [SDK reference](https://docs.livekit.io/reference/client-sdk-cpp/)
-- [Repository docs](./docs/README.md)
+- [Repository docs](./docs/README.md) — building, [authentication](./docs/authentication.md), testing, logging, tracing
 
 ## Using the SDK
 
@@ -187,9 +187,33 @@ room->addOnDataFrameCallback(sender_identity, "app-data",
 
 For end-to-end samples and a fuller set of demos, see the [cpp-example-collection repo](https://github.com/livekit-examples/cpp-example-collection).
 
+### Generating tokens
+
+For local development, install [`livekit-cli`](https://docs.livekit.io/home/cli/cli-setup/)
+and mint a participant JWT against a dev server (`livekit-server --dev` uses
+`devkey` / `secret`):
+
+```bash
+export LIVEKIT_URL=ws://localhost:7880
+export LIVEKIT_TOKEN=$(lk token create \
+  --api-key devkey \
+  --api-secret secret \
+  -i my-participant \
+  --join \
+  --valid-for 24h \
+  --room my-room \
+  --grant '{"canPublish":true,"canSubscribe":true,"canPublishData":true}' \
+  --token-only)
+```
+
+Pass `LIVEKIT_URL` and `LIVEKIT_TOKEN` into `Room::connect`, or use the SDK's
+token source helpers for endpoint, sandbox, and custom backends. See
+[docs/authentication.md](docs/authentication.md).
+
 ## Features
 
 - Connect to LiveKit rooms (Cloud or self-hosted)
+- Dynamic token sourcing (literal, custom, endpoint, sandbox, caching)
 - Receive remote audio/video tracks
 - Publish local audio/video tracks
 - Data tracks (low-level) and data streams (high-level)

cmake/nlohmann_json.cmake

@@ -0,0 +1,51 @@
+# cmake/nlohmann_json.cmake
+#
+# Windows: use vcpkg nlohmann-json
+# macOS/Linux: vendored nlohmann/json via FetchContent (header-only)
+#
+# Exposes:
+#   - Target nlohmann_json::nlohmann_json (INTERFACE, header-only)
+#
+# nlohmann/json is a PRIVATE dependency of liblivekit: it is only included from
+# implementation files under src/ and must never appear in a public header.
+# Its include directories are marked SYSTEM so its single ~25k-line header does
+# not trip -Wall/-Wextra/-Wpedantic or clang-tidy.
+
+include(FetchContent)
+include(warnings)
+
+set(LIVEKIT_NLOHMANN_JSON_VERSION "3.12.0" CACHE STRING "Vendored nlohmann/json version")
+
+# ---------------------------------------------------------------------------
+# Windows: use vcpkg
+# ---------------------------------------------------------------------------
+if(WIN32 AND LIVEKIT_USE_VCPKG)
+  find_package(nlohmann_json CONFIG REQUIRED)
+  if(TARGET nlohmann_json::nlohmann_json)
+    livekit_treat_as_external(nlohmann_json::nlohmann_json)
+  endif()
+  message(STATUS "Windows: using vcpkg nlohmann-json")
+  return()
+endif()
+
+# ---------------------------------------------------------------------------
+# macOS/Linux: vendored nlohmann/json via FetchContent
+# ---------------------------------------------------------------------------
+FetchContent_Declare(
+  livekit_nlohmann_json
+  URL "https://github.com/nlohmann/json/releases/download/v${LIVEKIT_NLOHMANN_JSON_VERSION}/json.tar.xz"
+  DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+)
+
+set(JSON_BuildTests OFF CACHE INTERNAL "")
+set(JSON_Install OFF CACHE INTERNAL "")
+
+livekit_fetchcontent_makeavailable(livekit_nlohmann_json)
+
+# Header-only INTERFACE target: nothing to compile, but mark its includes as
+# SYSTEM so warnings from json.hpp are suppressed in consuming targets.
+if(TARGET nlohmann_json::nlohmann_json)
+  livekit_treat_as_external(nlohmann_json::nlohmann_json)
+endif()
+
+message(STATUS "macOS/Linux: using vendored nlohmann/json v${LIVEKIT_NLOHMANN_JSON_VERSION}")

docker/Dockerfile.base

@@ -30,6 +30,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libasound2-dev \
     libabsl-dev \
     libclang-dev \
+    libcurl4-openssl-dev \
     libdrm-dev \
     libglib2.0-dev \
     libprotobuf-dev \

docs/README.md

@@ -4,6 +4,8 @@ Additional documentation for the SDK.
 
 - [Building](building.md) — prerequisites, build scripts, CMake presets,
   vcpkg, Docker, integration into your CMake project, troubleshooting.
+- [Authentication](authentication.md) — generating tokens, token source types
+  (initial connect only), and in-session token refresh.
 - [Logging](logging.md) — compile-time vs runtime filtering, log levels,
   custom sinks (file, JSON, ROS2 `RCLCPP_*` macros).
 - [Tracing](tracing.md) — Chromium-format performance traces, viewing in