Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions livekit-api/livekit/api/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,9 @@
TwirpErrorCode,
)
from .livekit_api import LiveKitAPI
from ._service import TokenSource
from ._service import TokenProvider
from .access_token import (
TokenGrants,
InferenceGrants,
ObservabilityGrants,
AgentGrants,
Expand All @@ -62,7 +63,8 @@

__all__ = [
"LiveKitAPI",
"TokenSource",
"TokenProvider",
"TokenGrants",
"room_service",
"egress_service",
"ingress_service",
Expand Down
14 changes: 7 additions & 7 deletions livekit-api/livekit/api/_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""


Expand All @@ -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
Expand All @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions livekit-api/livekit/api/access_token.py
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,13 @@ 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 as they are, and the server that
# signs the token converts them to the format of its key.
TokenGrants = Claims


class AccessToken:
ParticipantKind = Literal["standard", "egress", "ingress", "sip", "agent"]

Expand Down
20 changes: 10 additions & 10 deletions livekit-api/livekit/api/livekit_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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(
Expand Down
133 changes: 133 additions & 0 deletions tests/api/test_token_provider.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# 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."""

import asyncio
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"))


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)}"

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"

asyncio.run(run())


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"

asyncio.run(run())


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)


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())


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"

asyncio.run(run())
Loading