Playback security
Each channel decides who may watch it. A public channel plays for anyone with its URL. A token channel plays only with a short-lived token that your backend signs for each viewer, after your own sign-in or payment checks.
Public and token channels
Set the channel's Access in the Dashboard, or with --access public|token in the CLI. In token mode, every playback request carries the token:
| Output | Where the token goes |
|---|---|
| HLS and LL-HLS | ?token= on the multivariant playlist. Every child URL in it carries the token, so players need it only once. |
| WebRTC (WHEP) | Authorization: Bearer <token> or ?token= |
| Embed page, audio, thumbnail | ?token= |
| RTMP and SRT pull | rtmp://<host>/play/<channel>?token=…, srt://<host>:9000?streamid=read:<channel>:<token> |
The status JSON stays public in both modes, so pages can show whether a channel is live before a viewer signs in.
Playback keys
Tokens are signed with a playback key of the stream server, under Playback & webhooks or with hubfly stream playback-keys create. A server has up to 10. The key's secret is shown once, when it is created or rotated: store it where your backend reads secrets. The easiest way is a binding, which writes HUBFLY_STREAM_PLAYBACK_KEY_ID and HUBFLY_STREAM_PLAYBACK_KEY_SECRET into a Cell project and keeps them current when you rotate.
Sign on the server, never in the browser
NEXT_PUBLIC_, VITE_ or PUBLIC_ variable, and not in a mobile app.Sign tokens on your server
With @hubfly/streams/server (Node 18+, Bun, Deno and Cloudflare Workers), an endpoint that gives each signed-in viewer a one-hour token:
import { signPlaybackToken } from "@hubfly/streams/server";
export async function GET(request: Request) {
const user = await requireSignedInUser(request); // your own session check
const token = await signPlaybackToken(
{ id: process.env.HUBFLY_STREAM_PLAYBACK_KEY_ID!, secret: process.env.HUBFLY_STREAM_PLAYBACK_KEY_SECRET! },
{ ch: "sch_main0001", sub: user.id },
{ ttlSeconds: 3600 },
);
return Response.json({ token });
}In Go, with the standard-library streams package:
key := streams.PlaybackKey{
ID: os.Getenv("HUBFLY_STREAM_PLAYBACK_KEY_ID"),
Secret: os.Getenv("HUBFLY_STREAM_PLAYBACK_KEY_SECRET"),
}
token, err := streams.SignPlaybackToken(key, streams.PlaybackClaims{
Channel: "sch_main0001",
Expires: time.Now().Add(time.Hour).Unix(),
Subject: user.ID,
})Tokens are standard HS256 JWTs, so any JWT library can sign them with the key id as kid and the claims below. To try a channel without code, mint a test token in the channel's page or with hubfly stream channels token acme-tv Main --ttl 1h; test tokens need stream:operate and last at most 24 hours.
Pass the token to the player
<hubfly-player host="acme-tv.live.hubfly.app" channel="sch_main0001" autoplay muted></hubfly-player>
<script type="module">
import "@hubfly/streams/player";
const { token } = await fetch("/api/stream-token").then((response) => response.json());
document.querySelector("hubfly-player").setAttribute("token", token);
</script>For the embed page, add the token to its URL: https://acme-tv.live.hubfly.app/embed/sch_main0001?token=…. When a token is refused, the player shows an error with Try again: fetch a fresh token and set the attribute again.
Token claims and checks
| Claim | Required | Meaning |
|---|---|---|
ch | Yes | A channel id, or * for every channel of the server |
exp | Yes | Expiry in Unix seconds, at most 31 days ahead. The SDKs default to one hour. |
nbf, iat | No | Not before, issued at |
sub | No | Your viewer id (up to 128 characters), used only in viewer statistics |
ip | No | An IPv4 address or CIDR range the viewer must watch from |
The server accepts a token only when its algorithm is HS256, its kid names an active or retiring key of the same server, the signature is valid, it has not expired (30 seconds of clock skew are allowed), it names this channel, and the viewer's address matches ip if set. Any failure is a plain 401 that does not say which check failed.
A session that has started keeps playing until the token expires. HLS checks the token on every playlist request, so it stops within one playlist reload after expiry. Choose a lifetime that covers the event, or refresh the token in the page.
Rotate a playback key
Rotating a key creates a new one and marks the old key retiring for 24 hours: tokens signed with either work during that time, so viewers are not cut off. Bindings get the new key at once. After 24 hours the old key is revoked. To cut off every token at once, for example after a leak, delete the key instead.
hubfly stream playback-keys rotate acme-tv spk_key00001 # prints the new secret once
hubfly stream playback-keys delete acme-tv spk_key00001Origins, networks and viewer limits
- Allowed origins (per channel, or for the whole server under Settings): browsers on other sites are refused with
403. It discourages hotlinking but is not security on its own: tools outside a browser can send any origin. Use tokens to protect content. - Allowed networks: CIDR ranges viewers must watch from, for example an office or campus network.
- Viewer limit: new viewers beyond it get
503 viewer_limit; 0 means no limit. - WebRTC sessions per server (200 by default, up to 2,000): beyond it, new WebRTC viewers fall back to LL-HLS on their own.