LiveKit token endpoint

​

The contract is LiveKit’s own

​

What Egma sends

POST /egma/livekit-token HTTP/1.1
content-type: application/json
authorization: Bearer <the header you configured>

{
  "room_name": "egma-sim-sim_01K5TB2H8Y4P7QCWF9XKMD6RZN",
  "participant_identity": "egma-persona-sim_01K5TB2H8Y4P7QCWF9XKMD6RZN",
  "participant_name": "egma-persona-sim_01K5TB2H8Y4P7QCWF9XKMD6RZN",
  "room_config": {
    "agents": [
      { "agent_name": "front-desk", "metadata": "{\"tenant\":\"acme\"}" }
    ]
  }
}

• One request per simulation. No retry. A failed request ends the simulation with the reason.
• The auth headers go to this URL only. Egma does not follow redirects. It never logs a header value, and it scrubs the values out of anything it quotes.
• HTTPS to a public host only. Egma resolves the host again at request time and refuses private addresses. It waits 20 seconds for an answer and reads at most 64 KiB of it.
• One join, over TLS, to a public server. Egma joins once, as that identity, to that room, at the server URL you return. It holds that URL to the rule it holds your endpoint to: wss:// or https://, and a host that resolves to a public address. It publishes and subscribes audio. It waits 30 seconds for your worker to join and speak, then ends the simulation as agent_never_joined.
• Leave, never delete. Egma leaves when the conversation ends. It never deletes the room, and it never uses the token again.

​

What your endpoint returns

{
  "server_url": "wss://acme.livekit.cloud",
  "participant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

• Its identity is exactly participant_identity. The Egma SDK inside your worker addresses the persona by this identity for mock tools.
• It grants join on exactly room_name, with publish and subscribe. Leave data publishing allowed, which is the default. Mock tools use LiveKit RPC.
• It carries the room_config from the request as its room configuration. LiveKit reads that block only when the room is created, so do not create the room in your handler.
• It expires soon. A few minutes is enough.
• It carries no admin grants. No room create, room list, or room admin.

• Check the auth header on every request, in constant time. Answer 401 or 403 otherwise.
• Refuse a room_name that does not start with egma-sim-. Answer 4xx.
• Copy room_config into the token, or answer 4xx if you do not let a client name the worker. LiveKit’s own rule is 4xx for fields a client may not set. If you refuse it, your side must dispatch the worker another way: automatic dispatch, or an AgentDispatchService call in the same handler.
• Keep a short empty timeout on your project, so the room closes after Egma leaves.

​

A complete handler

import os
import secrets
from datetime import timedelta

from fastapi import FastAPI, Header, HTTPException
from google.protobuf.json_format import ParseDict
from livekit import api

app = FastAPI()
EGMA_SECRET = os.environ["EGMA_TOKEN_SECRET"]
LIVEKIT_URL = os.environ["LIVEKIT_URL"]


@app.post("/egma/livekit-token")
async def egma_token(body: dict, authorization: str = Header(default="")):
    # 1. Only Egma may ask.
    if not secrets.compare_digest(authorization, f"Bearer {EGMA_SECRET}"):
        raise HTTPException(401)

    # 2. Never a production room.
    room_name = body.get("room_name", "")
    if not room_name.startswith("egma-sim-"):
        raise HTTPException(400, "not a simulation room")

    # 3. Exactly the identity that asked, for exactly that room, for a few minutes.
    token = (
        api.AccessToken()  # reads LIVEKIT_API_KEY and LIVEKIT_API_SECRET
        .with_identity(body["participant_identity"])
        .with_name(body.get("participant_name", ""))
        .with_grants(
            api.VideoGrants(
                room_join=True, room=room_name, can_publish=True, can_subscribe=True
            )
        )
        .with_ttl(timedelta(minutes=5))
    )

    # 4. The worker Egma asked for, dispatched by LiveKit when the room is created.
    if "room_config" in body:
        token = token.with_room_config(
            ParseDict(body["room_config"], api.RoomConfiguration())
        )

    return {"server_url": LIVEKIT_URL, "participant_token": token.to_jwt()}

​

A development path with no code

• Token endpoint: https://cloud-api.livekit.io/api/v2/sandbox/connection-details
• Auth headers: {"X-Sandbox-ID": "<your token server id>"}

​

Registering the connection

curl -sX POST https://<your egma>/v1/agents \
  -H 'authorization: Bearer egma_sk_...' \
  -H 'content-type: application/json' \
  -d '{
    "name": "Front desk",
    "agentPlatform": "livekit",
    "connection": {
      "agentPlatform": "livekit",
      "connectionType": "livekit_room",
      "accessVariant": "livekit_room.customer_token_endpoint",
      "modality": "voice",
      "config": {
        "tokenEndpoint": "https://acme.example/egma/livekit-token",
        "agentName": "front-desk"
      },
      "credentials": {
        "headers": "{\"Authorization\":\"Bearer a-long-random-secret\"}"
      }
    }
  }'

• headers is a JSON object written inside a string. Put as many headers in it as your endpoint needs. Every value is treated as a secret.
• The headers are sealed and never come back. A read shows the header names only, as credentialsHint.
• A url key is refused. The connection holds no server URL, because your endpoint’s server_url is where Egma connects.

egma agent register --platform livekit --name "Front desk"

EGMA_LIVEKIT_TOKEN_ENDPOINT_HEADERS='{"Authorization":"Bearer a-long-random-secret"}' \
egma agent connection add \
  --agent agt_... \
  --access livekit-token-endpoint \
  --modality voice \
  --livekit-agent-name front-desk \
  --livekit-token-endpoint https://acme.example/egma/livekit-token

​

Hardening your endpoint

1. Require an auth header. Put a long random secret behind an Authorization header, check it on every request in constant time, and configure it on the Egma connection. An unauthenticated endpoint lets anyone who learns the URL mint tokens into your project. A URL is not a secret.
2. Mint for exactly the identity and room that were asked for. Do not substitute your own, do not append anything, and do not mint a wildcard.
3. Allowlist the egma-sim- prefix. Refuse any other room_name. Then refuse the same prefix everywhere else you mint a token, so a production room can never carry a name the Egma SDK reads as a simulation.
4. Give the token a short expiry. It is used once, seconds after it is minted.
5. Grant join, and nothing else. No room create, no room list, no admin.
6. Set a short empty timeout on your project. A minute or two. This is what closes the room after Egma leaves, because Egma cannot delete it.

​

What closes the room

​

When it does not work

• “the token endpoint at … could not be reached over HTTPS”: Egma could not open a connection. Check that the address is reachable from where Egma runs.
• “the token endpoint at … resolved to a non-public network address”: the hostname points inside a private network. Egma refuses those.
• “the token endpoint at … did not answer within 20 seconds”: your handler is too slow, or something in front of it is.
• “the token endpoint at … answered 401”, or any other non-2xx: your handler refused. Usually the auth header on the connection and the one your handler checks have drifted apart.
• “answered something that is not a JSON object”: usually a framework error page or a proxy’s HTML. The request never reached your handler, or it threw.
• “answered no token”: the body was JSON, but nothing in it was a token under participant_token or one of the other accepted names.
• “answered no server_url”: the body carried a token but no server. Add server_url to the answer.
• “answered a server_url Egma cannot join”: the server URL is not wss:// or https://, or carries credentials. Egma sends the token over TLS only.
• “answered a server_url on a non-public network address”: the server resolves inside a private network. Egma refuses it, as it refuses the endpoint itself. A self-hosted LiveKit on a private network uses project credentials instead.
• “no agent named … joined … nothing dispatched the agent”: the whole path worked and the room stayed empty. Your endpoint did not copy room_config into the token, or nothing else dispatched that worker, or no worker registered under that name is running.