Signed, expiring links
Signed links let your own application decide who may listen. Your app creates a link that works for a limited time; Quikcast only checks that it is genuine and not expired. There are no accounts, sessions or callbacks.
Typical uses: members-only streams, paid access, or a "listen now" button that works for an hour.
1. Share a key
Create a secret key that only your application and Quikcast know:
openssl rand -hex 32 > secrets/members-keyProtect the mount with it:
[[mounts]]
path = "/members.mp3"
secret_file = "secrets/members-source" # the encoder password, a different secret
[mounts.listener_auth]
type = "signed_url"
secret_file = "secrets/members-key"
max_ttl_seconds = 3600
clock_skew_seconds = 0| Setting | Meaning |
|---|---|
max_ttl_seconds | How far into the future a link may expire. Links asking for longer are refused. Default 86400 (a day), maximum one week. |
clock_skew_seconds | Extra time after expiry that is still accepted, to forgive clocks that disagree. 0–60, default 0. |
2. Sign links in your application
A link needs two query parameters: expires (a Unix timestamp in seconds) and sig (a signature). The signature is an HMAC-SHA-256 of this text, using your key:
<path>\n<expires>That's the mount path, a single newline, then the expiry number, with no trailing newline. The result is encoded as base64url without padding.
import { createHmac } from 'node:crypto'
export function signedUrl(base, path, key, ttlSeconds = 3600) {
const expires = Math.floor(Date.now() / 1000) + ttlSeconds
const sig = createHmac('sha256', key).update(`${path}\n${expires}`).digest('base64url')
return `${base}${path}?expires=${expires}&sig=${sig}`
}import base64, hashlib, hmac, time
def signed_url(base, path, key, ttl=3600):
expires = int(time.time()) + ttl
mac = hmac.new(key, f"{path}\n{expires}".encode(), hashlib.sha256).digest()
sig = base64.urlsafe_b64encode(mac).rstrip(b"=").decode()
return f"{base}{path}?expires={expires}&sig={sig}"function signedUrl(string $base, string $path, string $key, int $ttl = 3600): string {
$expires = time() + $ttl;
$mac = hash_hmac('sha256', "$path\n$expires", $key, true);
$sig = rtrim(strtr(base64_encode($mac), '+/', '-_'), '=');
return "$base$path?expires=$expires&sig=$sig";
}The key is the file's contents as text. If you made it with openssl rand -hex 32, the key is those 64 hex characters, not their decoded bytes.
3. Test your signer
Use this known-good example to check your code. With this key:
0123456789abcdef0123456789abcdefthe path /private-radio and expiry 1791504000 must produce:
VFu-3J9JLyvyAbZwMz_upmhVy0BouocqUWFd4ADtedYRules to remember
expiresis a plain number: no sign, spaces or leading zeros. The parameter names are exactlyexpiresandsig.- Any problem (bad signature, expired, too far in the future, duplicate parameters) gives the same
403 Forbidden. - Other query parameters are ignored and are not signed.
- With
previous_secret_filesorbind_ipthe same403covers a retired key or the wrong address. - Your server's clock must be right. Quikcast compares against its own clock.
- Don't log full URLs with their query strings in proxies or CDNs.
Rotate the key
Swapping the key at once would break every link already issued. Roll it over instead:
- Create the new key and make it
secret_file. List the old one underprevious_secret_files. - Reload (
kill -HUP). Links signed with either key now work. Start signing new links with the new key. - After the longest link you issued has expired (at most
max_ttl_seconds), remove the old key and reload again.
[mounts.listener_auth]
type = "signed_url"
secret_file = "secrets/members-key-2026-11"
previous_secret_files = ["secrets/members-key-2026-05"]Up to four previous keys are accepted. A leaked key stays valid until you remove it, so do not leave old keys listed longer than needed.
Revoke a single link
If one link leaks, you do not have to rotate the key and break everyone else's. Tell Quikcast to refuse that link, using its sig and expires values:
curl -X POST -H "Authorization: Bearer $QUIKCAST_TOKEN" \
"$QUIKCAST_ADMIN_URL/api/revocations?sig=VFu-3J9JLyvyAbZwMz_upmhVy0BouocqUWFd4ADtedY&expires=1791504000"The link then gets the same 403 as any bad link, on the stream, its playlists and HLS. The entry removes itself when the link would have expired anyway. Revocations are kept in memory, so they reset on restart (a link's life is short, but re-apply them after a restart if one matters) and they do not reach other nodes. A listener already playing is not cut off; use a ban with kick to end the session.
Bind links to an IP address
A signed link works for anyone who has it. To stop it being shared, add bind_ip = true. The link then only plays from the address it was signed for:
[mounts.listener_auth]
type = "signed_url"
secret_file = "secrets/members-key"
bind_ip = trueSign the listener's address as a third line:
<path>\n<expires>\n<ip>Use the address as text: dotted for IPv4 (203.0.113.7), compressed lowercase for IPv6 (2001:db8::1). An IPv4-mapped IPv6 address counts as its IPv4 address. With bind_ip on, links signed without an address are refused, and the reverse.
Know your trade-offs
Quikcast checks the address it sees, so behind a proxy configure trusted_proxies first, or every link will be checked against the proxy. Listeners on mobile networks can change address mid-session and will need a fresh link; for that reason, keep max_ttl_seconds short. Listeners behind shared NAT share an address.
const sig = createHmac('sha256', key).update(`${path}\n${expires}\n${listenerIp}`).digest('base64url')HLS streams
HLS streams can be protected the same way. The identity you sign is the stream's public path, for example /hls/members, no matter which playlist or segment is requested. One signature covers the master playlist, every rendition and all segments of that stream.
[hls.listener_auth."/hls/members"]
type = "signed_url"
secret_file = "secrets/members-key"Sign /hls/members and put expires and sig on the master playlist URL. Quikcast copies them into the playlist entries it generates, so players follow signed links all the way down.