- Rust 99.8%
- Dockerfile 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .cargo | ||
| .github | ||
| e2e-tests | ||
| integration-tests | ||
| src | ||
| tests | ||
| xtask | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Dockerfile | ||
| LICENSE | ||
| LICENSE-COMMERCIAL | ||
| README.md | ||
| renovate.json | ||
🎥 LiveKit Authorization Service
The LiveKit Authorization Service bridges Matrix and LiveKit, handling authentication, room creation and delegated delayed leave management when needed.
📌 When to Use
As per MSC4195, the connection between Matrix Clients and the LiveKit SFU is mediated by the homeserver. Homeservers can integrate lk-jwt-service as an application service to serve the LiveKit-related endpoints without adopting LiveKit as a dependency in the codebase.
For backwards compatibility, the service also supports the deprecated endpoints from prior versions of the MSC. These endpoints are the only ones served when lk-jwt-service is running in standalone mode, that is, not as an application service.
Caution
Not running as an application service is deprecated and support for it will be removed in future versions. It is strongly recommended to operate the service as an application service.
Caution
Fronting more than one homeserver via
LIVEKIT_FULL_ACCESS_HOMESERVERSis deprecated and will be removed in future versions. This setting only affects the legacy endpoints. It is strongly recommended to only put the one homeserver that lk-jwt-service was set up as an application service for intoLIVEKIT_FULL_ACCESS_HOMESERVERS.
Regardless of the above and as outlined in the Element Call Self-Hosting Guide, you’ll also need:
- A LiveKit SFU
- MatrixRTC-compatible clients such as
Element Call, which can run
either:
- As a standalone Single Page Application (SPA) or
- Embedded for in-app calling
✨ What It Does
🔑 Generates JWT tokens for a given LiveKit identity and room derived from the Matrix user and Matrix room, allowing users to authenticate with the LiveKit SFU.
🛡️ Manages user access levels to ensure the proper and secure use of infrastructure:
- Full-access users — Matrix users from homeservers in the same or related deployment as the MatrixRTC backend. Can trigger automatic LiveKit room creation if needed.
- Restricted users — All other Matrix users. Can join existing LiveKit SFU rooms, but cannot auto-create new ones.
🏗️ Auto-creates LiveKit rooms for full-access users if they don’t already exist.
Note
This setup ensures resources are used appropriately while still supporting seamless cross-federation MatrixRTC sessions, e.g., video calls. Remote users (not on the same deployment) can join existing rooms, but only full-access (local) users can trigger room creation. The SFU selection algorithm and event ordering ensure that conferences across Matrix federation remain fully functional.
⏰ Manages delegated delayed leave events to retain accurate session membership even when clients lose connectivity.
🚀 Installation
Releases are available here.
🐳 From Docker Image
docker run -e LIVEKIT_URL="ws://somewhere" -e LIVEKIT_KEY=devkey -e LIVEKIT_SECRET=secret -e LIVEKIT_FULL_ACCESS_HOMESERVERS=example.com -p 8080:8080 ghcr.io/element-hq/lk-jwt-service:latest
Which tag?
latestpoints at the most recent tagged release.latest-ciis a rolling build ofmain: it picks up every change immediately but may be unstable — use it only if you are comfortable running code that is under active development.
📦 From Release
- Download & mark as executable (example is amd64, replace with arm64 if needed):
wget https://github.com/element-hq/lk-jwt-service/releases/latest/download/lk-jwt-service_linux_amd64
chmod +x lk-jwt-service_linux_amd64
- Run locally:
LIVEKIT_URL="ws://somewhere" LIVEKIT_KEY=devkey LIVEKIT_SECRET=secret LIVEKIT_FULL_ACCESS_HOMESERVERS=example.com ./lk-jwt-service_linux_amd64
⚙️ Configuration
Set environment variables to configure the service:
| Variable | Description | Required | Default |
|---|---|---|---|
LIVEKIT_URL |
WebSocket URL of the LiveKit SFU | ✅ Yes | |
LIVEKIT_KEY / LIVEKIT_KEY_FROM_FILE |
API key or file path for LiveKit SFU | ✅ Yes | |
LIVEKIT_SECRET / LIVEKIT_SECRET_FROM_FILE |
API secret or file path for LiveKit SFU | ✅ Yes | |
LIVEKIT_KEY_FILE |
File path with APIkey: secret format |
⚠️ mutually exclusive with LIVEKIT_{KEY|SECRET} |
|
LIVEKIT_JWT_BIND |
Address to bind the server to, or /path for a unix socket |
❌ No, ⚠️ mutually exclusive with LIVEKIT_JWT_PORT |
:8080 |
LIVEKIT_JWT_PORT |
⚠️ Deprecated Port to bind the server to | ❌ No, ⚠️ mutually exclusive with LIVEKIT_JWT_BIND |
|
LIVEKIT_FULL_ACCESS_HOMESERVERS |
Comma-separated list of full-access homeservers (* for all — see security note below). Ignored when serving C-S and S-S endpoints as an application service. |
✅ Yes | |
LIVEKIT_REMOTE_CAN_PUBLISH_HOMESERVERS |
Comma-separated list of remote homeservers whose users may publish on the SFU when their token request is relayed over federation (* for all, empty for none — see Publishing from Other Homeservers). Only used when running as an application service. |
❌ No | * |
LIVEKIT_SANITY_CHECK_INTERVAL_SECONDS |
Interval (seconds) at which delegated-leave jobs re-check that a connected participant is still on the SFU. Guards against missed SFU webhooks. Unset/0 disables the sanity check. |
❌ No | 0 (disabled) |
LIVEKIT_CAN_UPDATE_OWN_METADATA |
When set to true, issued tokens grant participants the canUpdateOwnMetadata permission, allowing them to update their own name, metadata and attributes. Any other value disables the permission. |
❌ No | false |
LIVEKIT_LOG_LEVEL |
One of debug, info, warn/warning, error |
❌ No | info |
LIVEKIT_CS_API_URL_OVERRIDES |
Comma-separated list of overrides for Client-Server API locations that cannot be inferred using .well-known discovery (e.g. example.com=matrix-client.example.com) |
❌ No | |
LIVEKIT_REDIS_URL |
Redis connection URL (e.g. redis://localhost:6379). When set, service state will be persisted during operation and restored upon service restarts. When unset, the service falls back to an in-memory store. |
❌ No | |
LIVEKIT_REDIS_PASSWORD |
Redis password. While the password to Redis can be provided in LIVEKIT_REDIS_URL, this allows it to be provided independently. |
❌ No | |
LIVEKIT_AS_TOKEN |
The token used for authenticating requests to the homeserver as an application service | ❌ No, ⚠️ Required when running as an application service unless LIVEKIT_AS_REGISTRATION_FILE is set |
|
LIVEKIT_HS_TOKEN |
The token used by the homeserver for authenticating requests to the service as an application service | ❌ No, ⚠️ Required when running as an application service unless LIVEKIT_AS_REGISTRATION_FILE is set |
|
LIVEKIT_AS_REGISTRATION_FILE |
Path to an application service registration file containing the application service tokens. Takes precedence over LIVEKIT_AS_TOKEN and LIVEKIT_HS_TOKEN if specified. |
❌ No ⚠️ Required when running as an application service unless LIVEKIT_AS_TOKEN and LIVEKIT_HS_TOKEN are set |
|
LIVEKIT_HS_SERVER_NAME |
When running as an application service, the associated homeserver's server name. The C-S API needs to be resolvable from the server name. | ❌ No, ⚠️ Required when running as an application service |
Warning
Restricting room creation requires two pieces working together:
LIVEKIT_FULL_ACCESS_HOMESERVERSis matched against the requesting user's Matrix server name (origin). Listed origins may trigger LiveKit room creation on your SFU.*grants this to any user whose homeserver can reach this service; list the Matrix server name(s) of the homeserver(s) you intend to serve.- LiveKit SFU config.yaml must disable auto-create, otherwise LiveKit SFU will create rooms for any user regardless of what this service decides:
room: auto_create: false
🏠 Homeserver Wiring (Application Service)
When set up as an application service, the integration depends on
MSC4502 and
MSC4512. On Synapse, enable both
by setting msc4502_enabled: true and msc4512_enabled: true under experimental_features.
Neither of these proposals is part of the spec yet, so the service and Synapse use their unstable
identifiers (io.element.msc4502.* and io.element.msc4512.*).
MSC4195 has been accepted, and the service
serves its endpoints on the stable /_matrix/client/v1/rtc/livekit/… and /_matrix/federation/v1/rtc/livekit/…
paths. The unstable /_matrix/client/unstable/io.element.msc4195/… and /_matrix/federation/unstable/io.element.msc4195/…
paths are still served for clients and servers that haven't migrated yet. When relaying token requests to other
homeservers, the service uses the stable federation endpoint and falls back to the unstable one if the destination
doesn't recognise it.
The service needs to cover all local users because it needs to verify room memberships
without being joined to any rooms itself. This requires the urn:matrix:client:io.element.msc4502:rooms:is_joined
scope to be set via io.element.msc4502.scopes. The service does not require any event traffic, however. So make sure to set
url to null.
Additionally, request proxying needs to be enabled for the /rtc/livekit subpath in the Client-Server
and Server-Server API. This is done via the io.element.msc4512.proxy_prefix and
io.element.msc4512.proxy_url properties.
Running as an application service is also what allows the service to manage delegated delayed leave events on behalf of the homeserver's users (see LiveKit SFU Wiring).
Below is an example application service registration file.
id: "LiveKit JWT service"
as_token: "<snip>"
hs_token: "<snip>"
sender_localpart: "_lk_jwt_service"
namespaces:
users:
- exclusive: false
regex: ".*" # Cover all users
url: null # No event traffic required
# Scope for membership look-up
io.element.msc4502.scopes: [ "urn:matrix:client:io.element.msc4502:rooms:is_joined" ]
io.element.msc4512.proxy_prefix: "rtc/livekit" # Proxy /rtc/livekit requests on the C-S and S-S API
io.element.msc4512.proxy_url: "http://127.0.0.1:1234" # Forward proxied requests to this URL
🔒 Room Membership on the Standalone Endpoints
The endpoints that Synapse proxies (/_matrix/client/(unstable/io.element.msc4195|v1)/rtc/livekit/…) verify that the
requesting user is joined to the room. The standalone endpoints /sfu/get, /get_token and /delegate_delayed_leave,
however, only apply this check when the service runs as an application service and LIVEKIT_FULL_ACCESS_HOMESERVERS
names only the configured homeserver. Otherwise, with several full-access homeservers or *, sessions may exist in
rooms the application service's homeserver doesn't know about which makes it impossible to verify room membership.
This needs experimental_features.msc4502_enabled: true on Synapse and the
urn:matrix:client:io.element.msc4502:rooms:is_joined scope in the registration file (see
Homeserver Wiring), which the proxied endpoints require anyway.
📡 Publishing from Other Homeservers
MSC4195 optionally lets a client publish on an SFU of
another homeserver, discovered from a session member's m.rtc.member event. The client's homeserver relays the token
request to this service's S-S endpoint over federation, and the service decides whether the token grants publishing.
The MSC recommends allowing remote users to publish, which is the default. LIVEKIT_REMOTE_CAN_PUBLISH_HOMESERVERS
enables operators to narrow this to the listed homeservers or switch it off when set to an empty value. Users of
unlisted homeservers still get a token for subscribing though. Users of the configured homeserver always may publish,
through the C-S endpoint.
Room membership is verified for every relayed request, so remote publishers can only join sessions in rooms the configured homeserver is in. Note that any joined member of such a room, listed or not, can cause the LiveKit room to be created through a relayed request, since subscribers need it to exist too. Membership, not the list, is the guard there. Delayed leave delegation stays limited to the configured homeserver's own users.
🔌 LiveKit SFU Wiring (Webhooks)
Delegated MatrixRTC leave handling
(MSC4140)
relies on participant lifecycle events from the SFU. Point the LiveKit
SFU's webhook receiver at this service's /sfu_webhook endpoint in its
config.yaml:
webhook:
api_key: devkey # must match LIVEKIT_KEY used by this service —
# the SFU signs webhooks with it, this service verifies
urls:
- https://matrix-rtc.domain.tld/livekit/jwt/sfu_webhook
Note
- The URL is the public, reverse-proxied path to this service (see the TLS/reverse-proxy section below). For a local dev stack this is typically
https://matrix-rtc.m.localhost/livekit/jwt/sfu_webhook.webhook.api_keymust be one of the API keys the SFU knows (configured underkeys:in the SFU config) and must match theLIVEKIT_KEYthis service is started with. Webhook payloads are signed by the SFU and verified here.- Without this wiring,
/get_token,/sfu/getand/delegate_delayed_leavethe service cannot observe participant disconnects and therefore cannot send the delegated leave event. TheLIVEKIT_SANITY_CHECK_INTERVAL_SECONDSpull-based fallback partially mitigates this.
Important
Delegated delayed leave handling also requires running as an application service. The MSC4140 endpoints that restart and send a delayed event are authenticated and scoped to the user who scheduled it.
🔒 Transport Layer Security (TLS) Setup Using a Reverse Proxy
To properly secure the MatrixRTC Authorization Service, a reverse proxy is recommended.
Example Caddy Config
matrix-rtc.domain.tld {
bind xx.xx.xx.xx
handle /livekit/jwt* {
reverse_proxy localhost:8080
}
}
Example Nginx Config
server {
listen 80;
server_name matrix-rtc.domain.tld;
# Redirect HTTP → HTTPS
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name matrix-rtc.domain.tld;
# TLS certificate paths (replace with your own)
ssl_certificate /etc/ssl/certs/matrix-rtc.crt;
ssl_certificate_key /etc/ssl/private/matrix-rtc.key;
# TLS settings (minimal)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
location /livekit/jwt/ {
proxy_pass http://localhost:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
📌 Do Not Forget to Update Your Matrix Site's .well-known/matrix/client
For proper MatrixRTC functionality, you need to configure your site's
.well-known/matrix/client. See the
Element Call self-hosting guide
for reference.
The following key must be included in
https://domain.tld/.well-known/matrix/client:
"org.matrix.msc4143.rtc_foci": [
{
"type": "livekit",
"livekit_service_url": "https://matrix-rtc.domain.tld/livekit/jwt"
}
]
🧪 Development & Testing
Disable TLS verification
For testing and debugging (e.g. in the absence of trusted certificates while
testing in a lab), you can disable TLS verification for the outgoing connection
to the Matrix homeserver by setting the environment variable
LIVEKIT_INSECURE_SKIP_VERIFY_TLS to YES_I_KNOW_WHAT_I_AM_DOING.
🛠️ Development Environment (Docker Compose)
Based on the Element Call GitHub repo
The easiest way to spin up the full Matrix stack is by using the development environment provided by Element Call. For detailed instructions, see Element Call Backend Setup.
Note
To ensure your local frontend works properly, you need to add certificate exceptions in your browser for:
https://localhost:3000https://matrix-rtc.m.localhost/livekit/jwt/healthzhttps://synapse.m.localhost/.well-known/matrix/clientYou can do this either by adding the minimal m.localhost CA (dev_tls_m.localhost.crt) to your browser’s trusted certificates, or by visiting each URL in your browser and following the prompts to accept the exception.
🐳 Start MatrixRTC stack without the MatrixRTC Authorization Service
git clone https://github.com/element-hq/element-call.git
cd element-call
docker-compose -f ./dev-backend-docker-compose.yml -f ./playwright-backend-docker-compose.override.yml up nginx livekit synapse redis
🔑 Start the MatrixRTC Authorization Service locally
git clone https://github.com/element-hq/lk-jwt-service
cd lk-jwt-service
LIVEKIT_INSECURE_SKIP_VERIFY_TLS="YES_I_KNOW_WHAT_I_AM_DOING" \
LIVEKIT_URL="wss://matrix-rtc.m.localhost/livekit/sfu" \
LIVEKIT_KEY=devkey \
LIVEKIT_SECRET=secret \
LIVEKIT_JWT_PORT=6080 \
LIVEKIT_FULL_ACCESS_HOMESERVERS=synapse.m.localhost \
cargo run
🔨 Build from source
The service is written in Rust. With a Rust toolchain installed:
cargo build --release
# Produces target/release/lk-jwt-service and target/release/healthcheck
Run the test suite with:
cargo test
Develop inside container (docker, podman)
docker run --rm -it -w /proj -v .:/proj docker.io/rust:1-alpine sh
apk add --no-cache musl-dev cmake make gcc g++ perl linux-headers
cargo build --release
# The service binary is target/release/lk-jwt-service,
# the healthcheck binary is target/release/healthcheck