createAccessToken

Ce que ça fait

Construit et signe un jeton d’accès LiveKit (JWT), limité à une salle et à un rôle.

Signature

function createAccessToken(options: CreateAccessTokenOptions): Promise<AccessTokenResult>

Paramètres

Nom	Type	Requis	Défaut	Description
apiKey	string	oui	—	Clé API LiveKit
apiSecret	string	oui	—	Secret API LiveKit, jamais renvoyé ni journalisé
roomName	string	oui	—	Lettres, chiffres, ., _, - uniquement
identity	string	oui	—	Toute chaîne non vide, y compris Unicode
role	"host" | "participant" | "viewer"	oui	—	Détermine les permissions du jeton
ttlSeconds	number	non	DEFAULT_TOKEN_TTL_SECONDS	Durée de vie, doit être strictement positive
displayName	string	non	—	Nom affiché, distinct de identity ; mappé sur le champ natif name de LiveKit (Participant.name). Non vide si fourni.

Retour

Promise<{ token: string }> — le jeton JWT signé, prêt à être transmis au client.

Erreurs

Code	Quand	Comment corriger
LEGBA_INVALID_TOKEN_REQUEST	identity/roomName/displayName (si fourni) vide, roomName au format invalide, role hors énumération, ou ttlSeconds ≤ 0	Le message cite le champ et la valeur reçue

Exemple minimal

import { createAccessToken } from "@legba-core/realtime";

const { token } = await createAccessToken({
  apiKey: process.env.LIVEKIT_API_KEY!,
  apiSecret: process.env.LIVEKIT_API_SECRET!,
  roomName: "salle-demo",
  identity: "alice",
  role: "participant",
});

Exemple complet

import { createAccessToken, LegbaTokenError } from "@legba-core/realtime";

// À l'intérieur d'un gestionnaire de requête (Express, Fastify, ...) qui
// rend { token } ou { error } — ici isolé dans une fonction pour rester
// un exemple autonome.
async function issueToken() {
  try {
    const { token } = await createAccessToken({
      apiKey: process.env.LIVEKIT_API_KEY!,
      apiSecret: process.env.LIVEKIT_API_SECRET!,
      roomName: "salle-demo",
      identity: "alice",
      role: "viewer",
      ttlSeconds: 3600,
    });
    return { token };
  } catch (error) {
    if (error instanceof LegbaTokenError) {
      return { error: error.message };
    }
    throw error;
  }
}

Pièges

• Le serveur LiveKit applique une tolérance d’une minute sur l’expiration (exp) : un jeton n’est réellement refusé que passé ce délai, pas immédiatement à exp.
• Le nom de salle est validé contre un format strict (ROOM_NAME_PATTERN) : les espaces et caractères de contrôle sont refusés, jamais encodés silencieusement.
• displayName n’est qu’un nom affiché, jamais un identifiant : identity reste ce qui identifie réellement le participant partout ailleurs (participants, webhooks, modération). Composer un rôle métier + un nom affiché à partir d’une politique par tenant : voir la recette tenant-role-policy.md.

Voir aussi

• DEFAULT_TOKEN_TTL_SECONDS
• permissionsForRole
• LegbaTokenError
• resolveRole