# 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):

```bash
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):

```bash
# 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:

```yaml
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:

```bash
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.