From 19b1a9906eb15c372256c7f0aa0ef433097c87ef Mon Sep 17 00:00:00 2001 From: David Zhao Date: Sun, 15 Nov 2026 15:11:31 -0800 Subject: [PATCH 1/2] rename TokenSource -> TokenProvider to avoid confusion --- livekit-api/livekit/api/__init__.py | 8 +- livekit-api/livekit/api/_service.py | 14 +-- livekit-api/livekit/api/access_token.py | 12 +++ livekit-api/livekit/api/livekit_api.py | 20 ++-- tests/api/test_token_provider.py | 120 ++++++++++++++++++++++++ 5 files changed, 155 insertions(+), 19 deletions(-) create mode 100644 tests/api/test_token_provider.py diff --git a/livekit-api/livekit/api/__init__.py b/livekit-api/livekit/api/__init__.py index e31f6aeb..af0a97c9 100644 --- a/livekit-api/livekit/api/__init__.py +++ b/livekit-api/livekit/api/__init__.py @@ -44,8 +44,10 @@ TwirpErrorCode, ) from .livekit_api import LiveKitAPI -from ._service import TokenSource +from ._service import TokenProvider from .access_token import ( + TokenGrants, + token_grants_to_json, InferenceGrants, ObservabilityGrants, AgentGrants, @@ -62,7 +64,9 @@ __all__ = [ "LiveKitAPI", - "TokenSource", + "TokenProvider", + "TokenGrants", + "token_grants_to_json", "room_service", "egress_service", "ingress_service", diff --git a/livekit-api/livekit/api/_service.py b/livekit-api/livekit/api/_service.py index 6d63a9db..cca5eeb0 100644 --- a/livekit-api/livekit/api/_service.py +++ b/livekit-api/livekit/api/_service.py @@ -4,15 +4,15 @@ from abc import ABC from typing import Awaitable, Callable from .twirp_client import TwirpClient -from .access_token import AccessToken, Claims, VideoGrants, SIPGrants +from .access_token import AccessToken, Claims, TokenGrants, VideoGrants, SIPGrants AUTHORIZATION = "authorization" -TokenSource = Callable[[Claims], Awaitable[str]] -"""Returns a token that carries the given claims. +TokenProvider = Callable[[TokenGrants], Awaitable[str]] +"""Returns a token that carries the given grants. `LiveKitAPI` calls it before each request, in place of signing a token with an API -key and secret, with the claims that request needs. It may cache tokens. +key and secret, with the grants that request needs. It may cache tokens. """ @@ -32,7 +32,7 @@ def __init__( # skipping per-call signing. Per-service constructors stay key/secret-only. self._token: str | None = None # Set by LiveKitAPI to get a token per call in place of signing one. - self._token_source: TokenSource | None = None + self._token_provider: TokenProvider | None = None async def _auth_header( self, grants: VideoGrants | None, sip: SIPGrants | None = None @@ -41,8 +41,8 @@ async def _auth_header( if self._token: return {AUTHORIZATION: "Bearer {}".format(self._token)} - if self._token_source is not None: - token = await self._token_source(Claims(video=grants, sip=sip)) + if self._token_provider is not None: + token = await self._token_provider(Claims(video=grants, sip=sip)) return {AUTHORIZATION: "Bearer {}".format(token)} tok = AccessToken(self.api_key, self.api_secret) diff --git a/livekit-api/livekit/api/access_token.py b/livekit-api/livekit/api/access_token.py index 22498380..2719bf89 100644 --- a/livekit-api/livekit/api/access_token.py +++ b/livekit-api/livekit/api/access_token.py @@ -178,6 +178,18 @@ def asdict(self) -> dict: return claims +# The grants that a `TokenProvider` is asked for. Today these are v1 claims +# (`Claims`). Grants v2 will be accepted here too. The provider does not convert +# between the two: it passes the grants on with `token_grants_to_json`, and the +# server that signs the token converts them to the format of its key. +TokenGrants = Claims + + +def token_grants_to_json(grants: TokenGrants) -> str: + """Returns the grants as JSON, in the shape of an access token's payload.""" + return json.dumps(grants.asdict()) + + class AccessToken: ParticipantKind = Literal["standard", "egress", "ingress", "sip", "agent"] diff --git a/livekit-api/livekit/api/livekit_api.py b/livekit-api/livekit/api/livekit_api.py index 0eaa22fc..8c62b649 100644 --- a/livekit-api/livekit/api/livekit_api.py +++ b/livekit-api/livekit/api/livekit_api.py @@ -6,7 +6,7 @@ from .sip_service import SipService from .agent_dispatch_service import AgentDispatchService from .connector_service import ConnectorService -from ._service import TokenSource +from ._service import TokenProvider from typing import Any, Optional @@ -31,7 +31,7 @@ def __init__( api_secret: Optional[str] = None, *, token: Optional[str] = None, - token_source: Optional[TokenSource] = None, + token_provider: Optional[TokenProvider] = None, timeout: Optional[aiohttp.ClientTimeout] = None, session: Optional[aiohttp.ClientSession] = None, failover: bool = True, @@ -47,7 +47,7 @@ def __init__( api_key: API key (read from `LIVEKIT_API_KEY` environment variable if not provided) api_secret: API secret (read from `LIVEKIT_API_SECRET` environment variable if not provided) token: Pre-signed access token (read from `LIVEKIT_TOKEN` environment variable if not provided) - token_source: Async callable that returns a token for the claims of each call, + token_provider: Async callable that returns a token for the grants of each call, in place of signing one with api_key and api_secret timeout: Request timeout (default: 10 seconds) session: aiohttp.ClientSession instance to use for requests, if not provided, a new one will be created @@ -57,19 +57,19 @@ def __init__( # Only fall back to environment credentials when none were provided # explicitly, so an ambient LIVEKIT_TOKEN can't silently override an # explicit api_key/secret (or vice versa). - if not token and not token_source and not api_key and not api_secret: + if not token and not token_provider and not api_key and not api_secret: token = os.getenv("LIVEKIT_TOKEN") - if not token and not token_source and not api_key and not api_secret: + if not token and not token_provider and not api_key and not api_secret: api_key = os.getenv("LIVEKIT_API_KEY") api_secret = os.getenv("LIVEKIT_API_SECRET") if not url: raise ValueError("url must be set") - if token and token_source: - raise ValueError("token and token_source cannot both be set") + if token and token_provider: + raise ValueError("token and token_provider cannot both be set") - if not token and not token_source and (not api_key or not api_secret): + if not token and not token_provider and (not api_key or not api_secret): raise ValueError("either token, or api_key and api_secret, must be set") self._custom_session = True @@ -91,7 +91,7 @@ def __init__( self._agent_dispatch = AgentDispatchService(self._session, url, key, secret, failover) self._connector = ConnectorService(self._session, url, key, secret, failover) - if token or token_source: + if token or token_provider: for svc in ( self._room, self._ingress, @@ -101,7 +101,7 @@ def __init__( self._connector, ): svc._token = token - svc._token_source = token_source + svc._token_provider = token_provider @classmethod def with_token( diff --git a/tests/api/test_token_provider.py b/tests/api/test_token_provider.py new file mode 100644 index 00000000..ee73708f --- /dev/null +++ b/tests/api/test_token_provider.py @@ -0,0 +1,120 @@ +# 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. + +"""How LiveKitAPI authenticates each call: with a token provider, an API key and +secret, or a static token. A recording session stands in for the server.""" + +from typing import Dict, List + +import jwt +import pytest + +from livekit import api +from livekit.api.access_token import Claims +from livekit.protocol.room import ListParticipantsRequest, ListParticipantsResponse + +URL = "http://localhost:7880" +KEY, SECRET = "devkey", "thiskeyistotallyunsafe-but-32-bytes-long" + + +class _Response: + status = 200 + + async def read(self) -> bytes: + return ListParticipantsResponse().SerializeToString() + + +class _Post: + async def __aenter__(self) -> _Response: + return _Response() + + async def __aexit__(self, *exc) -> None: + return None + + +class _RecordingSession: + timeout = None + + def __init__(self) -> None: + self.headers: List[Dict[str, str]] = [] + + def post(self, url: str, *, headers: Dict[str, str], **kwargs) -> _Post: + self.headers.append(headers) + return _Post() + + +def _bearer(session: _RecordingSession) -> str: + return session.headers[-1]["authorization"].removeprefix("Bearer ") + + +async def _list_participants(lk: api.LiveKitAPI) -> None: + await lk.room.list_participants(ListParticipantsRequest(room="test-room")) + + +async def test_token_provider_gets_the_grants_of_each_call() -> None: + requested: List[api.TokenGrants] = [] + + async def token_provider(grants: api.TokenGrants) -> str: + requested.append(grants) + return f"provider-token-{len(requested)}" + + session = _RecordingSession() + lk = api.LiveKitAPI(URL, token_provider=token_provider, session=session) # type: ignore[arg-type] + + await _list_participants(lk) + assert requested == [Claims(video=api.VideoGrants(room_admin=True, room="test-room"))] + assert _bearer(session) == "provider-token-1" + + await lk.sip.list_inbound_trunk(api.ListSIPInboundTrunkRequest()) + assert requested[-1] == Claims(video=api.VideoGrants(), sip=api.SIPGrants(admin=True)) + assert _bearer(session) == "provider-token-2" + + +async def test_token_provider_takes_precedence_over_env(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("LIVEKIT_TOKEN", "env-token") + monkeypatch.setenv("LIVEKIT_API_KEY", KEY) + monkeypatch.setenv("LIVEKIT_API_SECRET", SECRET) + + async def token_provider(grants: api.TokenGrants) -> str: + return "provider-token" + + session = _RecordingSession() + lk = api.LiveKitAPI(URL, token_provider=token_provider, session=session) # type: ignore[arg-type] + await _list_participants(lk) + assert _bearer(session) == "provider-token" + + +def test_token_and_token_provider_are_exclusive() -> None: + async def token_provider(grants: api.TokenGrants) -> str: + return "provider-token" + + with pytest.raises(ValueError, match="cannot both be set"): + api.LiveKitAPI(URL, token="static", token_provider=token_provider) + + +async def test_key_and_secret_sign_each_call() -> None: + session = _RecordingSession() + lk = api.LiveKitAPI(URL, KEY, SECRET, session=session) # type: ignore[arg-type] + await _list_participants(lk) + + claims = api.TokenVerifier(KEY, SECRET).verify(_bearer(session)) + assert claims.video == api.VideoGrants(room_admin=True, room="test-room") + assert jwt.decode(_bearer(session), options={"verify_signature": False})["iss"] == KEY + + +async def test_static_token_is_sent_verbatim() -> None: + session = _RecordingSession() + lk = api.LiveKitAPI.with_token("static-token", URL, session=session) # type: ignore[arg-type] + await _list_participants(lk) + assert _bearer(session) == "static-token" From 07359e0a91852984bff85f96a4e4b10872a73b7c Mon Sep 17 00:00:00 2001 From: David Zhao Date: Sun, 15 Nov 2026 17:26:13 -0800 Subject: [PATCH 2/2] fix tests --- livekit-api/livekit/api/__init__.py | 2 - livekit-api/livekit/api/access_token.py | 9 +-- tests/api/test_token_provider.py | 83 ++++++++++++++----------- 3 files changed, 50 insertions(+), 44 deletions(-) diff --git a/livekit-api/livekit/api/__init__.py b/livekit-api/livekit/api/__init__.py index af0a97c9..1bf3105c 100644 --- a/livekit-api/livekit/api/__init__.py +++ b/livekit-api/livekit/api/__init__.py @@ -47,7 +47,6 @@ from ._service import TokenProvider from .access_token import ( TokenGrants, - token_grants_to_json, InferenceGrants, ObservabilityGrants, AgentGrants, @@ -66,7 +65,6 @@ "LiveKitAPI", "TokenProvider", "TokenGrants", - "token_grants_to_json", "room_service", "egress_service", "ingress_service", diff --git a/livekit-api/livekit/api/access_token.py b/livekit-api/livekit/api/access_token.py index 2719bf89..74dddafd 100644 --- a/livekit-api/livekit/api/access_token.py +++ b/livekit-api/livekit/api/access_token.py @@ -180,16 +180,11 @@ def asdict(self) -> dict: # The grants that a `TokenProvider` is asked for. Today these are v1 claims # (`Claims`). Grants v2 will be accepted here too. The provider does not convert -# between the two: it passes the grants on with `token_grants_to_json`, and the -# server that signs the token converts them to the format of its key. +# between the two: it passes the grants on as they are, and the server that +# signs the token converts them to the format of its key. TokenGrants = Claims -def token_grants_to_json(grants: TokenGrants) -> str: - """Returns the grants as JSON, in the shape of an access token's payload.""" - return json.dumps(grants.asdict()) - - class AccessToken: ParticipantKind = Literal["standard", "egress", "ingress", "sip", "agent"] diff --git a/tests/api/test_token_provider.py b/tests/api/test_token_provider.py index ee73708f..ce3c16b3 100644 --- a/tests/api/test_token_provider.py +++ b/tests/api/test_token_provider.py @@ -15,6 +15,7 @@ """How LiveKitAPI authenticates each call: with a token provider, an API key and secret, or a static token. A recording session stands in for the server.""" +import asyncio from typing import Dict, List import jwt @@ -62,37 +63,43 @@ async def _list_participants(lk: api.LiveKitAPI) -> None: await lk.room.list_participants(ListParticipantsRequest(room="test-room")) -async def test_token_provider_gets_the_grants_of_each_call() -> None: - requested: List[api.TokenGrants] = [] +def test_token_provider_gets_the_grants_of_each_call() -> None: + async def run() -> None: + requested: List[api.TokenGrants] = [] - async def token_provider(grants: api.TokenGrants) -> str: - requested.append(grants) - return f"provider-token-{len(requested)}" + async def token_provider(grants: api.TokenGrants) -> str: + requested.append(grants) + return f"provider-token-{len(requested)}" - session = _RecordingSession() - lk = api.LiveKitAPI(URL, token_provider=token_provider, session=session) # type: ignore[arg-type] + session = _RecordingSession() + lk = api.LiveKitAPI(URL, token_provider=token_provider, session=session) # type: ignore[arg-type] - await _list_participants(lk) - assert requested == [Claims(video=api.VideoGrants(room_admin=True, room="test-room"))] - assert _bearer(session) == "provider-token-1" + await _list_participants(lk) + assert requested == [Claims(video=api.VideoGrants(room_admin=True, room="test-room"))] + assert _bearer(session) == "provider-token-1" - await lk.sip.list_inbound_trunk(api.ListSIPInboundTrunkRequest()) - assert requested[-1] == Claims(video=api.VideoGrants(), sip=api.SIPGrants(admin=True)) - assert _bearer(session) == "provider-token-2" + await lk.sip.list_inbound_trunk(api.ListSIPInboundTrunkRequest()) + assert requested[-1] == Claims(video=api.VideoGrants(), sip=api.SIPGrants(admin=True)) + assert _bearer(session) == "provider-token-2" + asyncio.run(run()) -async def test_token_provider_takes_precedence_over_env(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setenv("LIVEKIT_TOKEN", "env-token") - monkeypatch.setenv("LIVEKIT_API_KEY", KEY) - monkeypatch.setenv("LIVEKIT_API_SECRET", SECRET) - async def token_provider(grants: api.TokenGrants) -> str: - return "provider-token" +def test_token_provider_takes_precedence_over_env(monkeypatch: pytest.MonkeyPatch) -> None: + async def run() -> None: + monkeypatch.setenv("LIVEKIT_TOKEN", "env-token") + monkeypatch.setenv("LIVEKIT_API_KEY", KEY) + monkeypatch.setenv("LIVEKIT_API_SECRET", SECRET) + + async def token_provider(grants: api.TokenGrants) -> str: + return "provider-token" - session = _RecordingSession() - lk = api.LiveKitAPI(URL, token_provider=token_provider, session=session) # type: ignore[arg-type] - await _list_participants(lk) - assert _bearer(session) == "provider-token" + session = _RecordingSession() + lk = api.LiveKitAPI(URL, token_provider=token_provider, session=session) # type: ignore[arg-type] + await _list_participants(lk) + assert _bearer(session) == "provider-token" + + asyncio.run(run()) def test_token_and_token_provider_are_exclusive() -> None: @@ -103,18 +110,24 @@ async def token_provider(grants: api.TokenGrants) -> str: api.LiveKitAPI(URL, token="static", token_provider=token_provider) -async def test_key_and_secret_sign_each_call() -> None: - session = _RecordingSession() - lk = api.LiveKitAPI(URL, KEY, SECRET, session=session) # type: ignore[arg-type] - await _list_participants(lk) +def test_key_and_secret_sign_each_call() -> None: + async def run() -> None: + session = _RecordingSession() + lk = api.LiveKitAPI(URL, KEY, SECRET, session=session) # type: ignore[arg-type] + await _list_participants(lk) + + claims = api.TokenVerifier(KEY, SECRET).verify(_bearer(session)) + assert claims.video == api.VideoGrants(room_admin=True, room="test-room") + assert jwt.decode(_bearer(session), options={"verify_signature": False})["iss"] == KEY + + asyncio.run(run()) - claims = api.TokenVerifier(KEY, SECRET).verify(_bearer(session)) - assert claims.video == api.VideoGrants(room_admin=True, room="test-room") - assert jwt.decode(_bearer(session), options={"verify_signature": False})["iss"] == KEY +def test_static_token_is_sent_verbatim() -> None: + async def run() -> None: + session = _RecordingSession() + lk = api.LiveKitAPI.with_token("static-token", URL, session=session) # type: ignore[arg-type] + await _list_participants(lk) + assert _bearer(session) == "static-token" -async def test_static_token_is_sent_verbatim() -> None: - session = _RecordingSession() - lk = api.LiveKitAPI.with_token("static-token", URL, session=session) # type: ignore[arg-type] - await _list_participants(lk) - assert _bearer(session) == "static-token" + asyncio.run(run())