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:

sh
openssl rand -hex 32 > secrets/members-key

Protect the mount with it:

toml
[[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
SettingMeaning
max_ttl_secondsHow far into the future a link may expire. Links asking for longer are refused. Default 86400 (a day), maximum one week.
clock_skew_secondsExtra time after expiry that is still accepted, to forgive clocks that disagree. 0–60, default 0.

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:

text
<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.

js
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}`
}
python
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}"
php
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:

text
0123456789abcdef0123456789abcdef

the path /private-radio and expiry 1791504000 must produce:

text
VFu-3J9JLyvyAbZwMz_upmhVy0BouocqUWFd4ADtedY

Rules to remember ​

  • expires is a plain number: no sign, spaces or leading zeros. The parameter names are exactly expires and sig.
  • 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_files or bind_ip the same 403 covers 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:

  1. Create the new key and make it secret_file. List the old one under previous_secret_files.
  2. Reload (kill -HUP). Links signed with either key now work. Start signing new links with the new key.
  3. After the longest link you issued has expired (at most max_ttl_seconds), remove the old key and reload again.
toml
[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.

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:

sh
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.

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:

toml
[mounts.listener_auth]
type = "signed_url"
secret_file = "secrets/members-key"
bind_ip = true

Sign the listener's address as a third line:

text
<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.

js
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.

toml
[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.