LiveKit Token Server — Sign JWTs for Room Access

简介

LiveKit room 要签名 JWT 访问 token —— 后端用 API key + secret 签 token，授权某个身份以指定权限（publish / subscribe / record / data）加入指定 room。绝对不要在浏览器里签。这是 Python 和 Node 服务端流程。适合任何生产 LiveKit 部署、多租户语音应用、按用户的权限模型。兼容 livekit-server-sdk（Python / Node / Go / Ruby / Java）。装机时间 10 分钟。

Python token endpoint（FastAPI）

from livekit import api
from fastapi import FastAPI, HTTPException, Depends
import os

app = FastAPI()

@app.post("/livekit/token")
async def issue_token(user_id: str, room: str, user = Depends(authenticated_user)):
    if not can_join_room(user, room):
        raise HTTPException(403, "无权进入该 room")

    token = (
        api.AccessToken(os.environ["LIVEKIT_API_KEY"], os.environ["LIVEKIT_API_SECRET"])
        .with_identity(user_id)
        .with_name(user.display_name)
        .with_grants(api.VideoGrants(
            room_join=True,
            room=room,
            can_publish=True,
            can_subscribe=True,
            can_publish_data=True,
        ))
        .with_ttl(timedelta(hours=1))
        .to_jwt()
    )
    return {"token": token, "url": os.environ["LIVEKIT_URL"]}

Node token endpoint（Express）

import { AccessToken } from 'livekit-server-sdk';

app.post('/livekit/token', requireAuth, async (req, res) => {
  const { userId, room } = req.body;
  if (!canJoinRoom(req.user, room)) return res.status(403).send();

  const at = new AccessToken(process.env.LIVEKIT_API_KEY, process.env.LIVEKIT_API_SECRET, {
    identity: userId,
    name: req.user.displayName,
    ttl: '1h',
  });
  at.addGrant({
    roomJoin: true,
    room,
    canPublish: true,
    canSubscribe: true,
    canPublishData: true,
  });

  res.json({ token: await at.toJwt(), url: process.env.LIVEKIT_URL });
});

Grant cheat sheet

生产加固

• 短 TTL —— 终端用户 token 最多 1 小时。浏览器通过 endpoint 续签。
• 按用户 identity —— 别复用 identity。user_id 应是 DB 主键。
• 仅服务端 —— 不打 secret 日志、绝不把 API_SECRET 发到浏览器。
• 缓存 SDK —— 实例化一次，签多次复用。

FAQ

Q: 能在浏览器签 token 吗？ A: 不能 —— API_SECRET 会暴露。永远在后端签。浏览器只见结果 JWT，TTL 受限、grant 限定。

Q: agent 怎么拿自己的 token？ A: agent 同样认证 —— worker 进程签 agent 身份 token（带 agent=True grant）再加入 room。LiveKit Cloud agent 调度器在你用 LiveKit CLI 部署时自动处理。

Q: participant join/leave 的 webhook 呢？ A: 在 cloud.livekit.io → Webhooks 配置。事件：room_started / participant_joined / participant_left / track_published / egress_started。服务端验 X-LiveKit-Signature header。