LiveKit Server SDK

Common errors

• Error: signature verification failed

  cause Incorrect LiveKit API Key or API Secret provided to the AccessToken constructor or when creating a WebhookReceiver.
  fix Double-check your `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` environment variables or constructor arguments. Ensure they match the credentials from your LiveKit Cloud project or self-hosted instance.

• TypeError: app.use() requires callback functions but got a [object Undefined]

  cause Often seen in Express.js applications when trying to use middleware like `express.raw()` without importing it correctly or if Express.js is not initialized properly, specifically when handling webhook bodies.
  fix Ensure `express` is imported and `express.raw()` is correctly configured for the webhook endpoint: `import express from 'express'; const app = express(); app.use(express.raw({type: 'application/webhook+json'}));`

• ERR_REQUIRE_ESM: require() of ES Module <...>/livekit-server-sdk.js from <your-file>.js not supported

  cause Attempting to use CommonJS `require()` syntax with `livekit-server-sdk` v2+ in a Node.js project that is configured for ES Modules, or vice-versa with a mixed configuration.
  fix If your project is ESM-first (e.g., `"type": "module"` in `package.json`), use `import { ... } from 'livekit-server-sdk';`. If your project is CJS, you might need to ensure your transpilation setup is correct or check if an older CJS-compatible version is available (though v2 is primarily ESM).

Warnings

• breaking The SDK underwent a major rewrite from v1.x to v2.x, introducing breaking changes in API structure and package exports. Users migrating from v1 will need to review the dedicated migration guide.
  Fix: Consult the official LiveKit Server SDK v2 migration guide for detailed instructions on updating your codebase.
• gotcha Exposing LiveKit API keys and secrets in client-side code (e.g., browsers) is a severe security risk. This SDK should ONLY be used in secure server-side environments.
  Fix: Ensure that the `livekit-server-sdk` is only used on your backend, and that API keys/secrets are managed securely (e.g., environment variables, secret management services) and never transmitted to the client.
• gotcha When integrating webhooks, ensure your HTTP server is configured to correctly parse `application/webhook+json` content type. Standard JSON parsers (e.g., `express.json()`) may not work.
  Fix: For Express.js, use `app.use(express.raw({type: 'application/webhook+json'}));` before your webhook route handler to get the raw body string required by `WebhookReceiver` for verification.

Install

• npm install livekit-server-sdk npm
• yarn add livekit-server-sdk yarn
• pnpm add livekit-server-sdk pnpm

Imports

• AccessToken
  wrong:

  const AccessToken = require('livekit-server-sdk').AccessToken;

  correct:

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

  The v2 SDK is primarily designed for ESM usage. While CJS might work via transpilation, direct require() is not the recommended or native way for Node.js >=18.
• RoomServiceClient
  wrong:

  const { RoomServiceClient } = require('livekit-server-sdk');

  correct:

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

  Used for managing LiveKit rooms (list, create, delete) and participants. Requires API key and secret.
• WebhookReceiver
  wrong:

  import WebhookReceiver from 'livekit-server-sdk';

  correct:

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

  This is a named export, not a default export. Used for decoding and verifying LiveKit webhook callbacks.

Quickstart

Demonstrates how to generate an access token for a LiveKit participant to join a specified room, including setting basic permissions and token expiration.

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

// Load API keys from environment variables for security.
// NEVER hardcode secrets in production code.
const LIVEKIT_API_KEY = process.env.LIVEKIT_API_KEY ?? '';
const LIVEKIT_API_SECRET = process.env.LIVEKIT_API_SECRET ?? '';

const roomName = 'my-dynamic-room-' + Math.random().toString(36).substring(7);
const participantIdentity = 'user-' + Math.random().toString(36).substring(7);

async function generateLiveKitToken() {
  if (!LIVEKIT_API_KEY || !LIVEKIT_API_SECRET) {
    console.error('LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set as environment variables or provided directly.');
    return;
  }

  const at = new AccessToken(LIVEKIT_API_KEY, LIVEKIT_API_SECRET, {
    identity: participantIdentity,
    name: `User ${participantIdentity.substring(5)}`,
    ttl: '1h', // Token expires in 1 hour
  });

  at.addGrant({
    roomJoin: true,
    room: roomName,
    canPublish: true,      // Participant can publish audio/video
    canSubscribe: true,    // Participant can subscribe to others' tracks
    canUpdateOwnMetadata: true,
    // Additional permissions like canPublishSources, canUpdateRoom, etc., can be added here
  });

  const token = await at.toJwt();
  console.log(`Generated LiveKit Access Token for participant '${participantIdentity}' in room '${roomName}':`);
  console.log(token);
  console.log('\nThis token can be used by a LiveKit client SDK to join the room.');
}

generateLiveKitToken().catch(console.error);