AvanzaCast/packages/backend-api/README.DEBUG.md

Debugging backend-api: enable token header debug

This small guide shows how to enable JWT debug headers in /api/session/:id/token responses.

What it does

• When ALLOW_DEBUG_TOKEN_HEADER=1 or NODE_ENV=development, the backend will include debugHeader in the JSON response for /api/session/:id/token.
• This helps to inspect alg, typ and other header fields when LiveKit rejects tokens.

How to enable locally

1. Copy the debug env file (optional):

cd packages/backend-api
cp .env.debug .env
# Edit .env to set LIVEKIT_API_SECRET or LIVEKIT_API_KEY if required

2. Start the backend in development mode (or restart if it's already running):

# if you run directly with node
npm install
npm run dev

# or if you use ts-node / nodemon adjust accordingly

How to enable in docker-compose

• If backend-api runs in docker-compose, set environment in the compose file or use an env_file:

services:
  backend-api:
    image: ...
    env_file:
      - packages/backend-api/.env.debug

Then docker compose up -d backend-api.

How to test

1. Create or obtain a session id from the token server or the UI.
2. Request token details with debug:

curl -s "http://localhost:4000/api/session/<id>/token" | jq .

Look for debugHeader and debugVerifyHS256 fields.

If you prefer I can (A) add an endpoint /debug/verify-token that runs jwt verify using the configured secret (only when ALLOW_DEBUG_TOKEN_HEADER=1) or (B) prepare a docker-compose snippet that injects the debug env automatically. Reply A or B to proceed.