Add token source API for fetching LiveKit tokens (#177)

* Adds new public API token_source.h, allowing users to now mint tokens using the following paths:
  * Literal: user-provided token (basically the legacy livekit-cli minted path)
  * Sandbox: enable a sandbox token server via LiveKit cloud, and allow users insecurely mint tokens (development only)
  * Endpoint: production-level server support
  * Custom: additional user token minting support

Author: alan-george-lk

.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/ci.yml

@@ -101,14 +101,14 @@ jobs:
   docker-images:
     name: Docker Images
     needs: changes
-    if: ${{ (github.event_name == 'pull_request' && needs.changes.outputs.docker == 'true') || github.event_name == 'workflow_dispatch' }}
+    if: ${{ (github.event_name == 'pull_request' && needs.changes.outputs.docker == 'true') || (github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.changes.outputs.docker == 'true') || github.event_name == 'workflow_dispatch' }}
     permissions:
       contents: read
       actions: read
       packages: write
     uses: ./.github/workflows/docker-images.yml
     with:
-      push_images: false
+      push_images: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
     secrets: inherit
 
   tests:

.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/docker-images.yml

@@ -200,6 +200,9 @@ jobs:
             docker push "${base_image}:${sha_tag}-amd64"
           fi
 
+          docker tag livekit-cpp-sdk-base-x64:${{ github.sha }} "${base_image}:base-main-amd64"
+          docker push "${base_image}:base-main-amd64"
+
       - name: Push SDK image (amd64)
         if: ${{ inputs.push_images }}
         shell: bash
@@ -328,6 +331,9 @@ jobs:
             docker push "${base_image}:${sha_tag}-arm64"
           fi
 
+          docker tag livekit-cpp-sdk-base-arm64:${{ github.sha }} "${base_image}:base-main-arm64"
+          docker push "${base_image}:base-main-arm64"
+
       - name: Push SDK image (arm64)
         if: ${{ inputs.push_images }}
         shell: bash
@@ -523,6 +529,11 @@ jobs:
               "${base_image}:${sha_tag}-arm64"
           fi
 
+          docker buildx imagetools create \
+            -t "${base_image}:base-main" \
+            "${base_image}:base-main-amd64" \
+            "${base_image}:base-main-arm64"
+
   publish-sdk-manifest:
     name: Publish SDK manifest
     runs-on: ubuntu-latest

.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
 
@@ -215,7 +216,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
@@ -255,12 +255,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
@@ -272,6 +282,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()
@@ -336,6 +351,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.
@@ -401,6 +402,13 @@ all filtered stages; normal pull requests and pushes use the path filters.
 - `.github/workflows/docker-images.yml` — Reusable Docker image smoke-test and
   publish workflow (optional push via input), called by CI and release workflows.
 
+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"
       }
     },
     {