Signed URLs: Authenticating Livry Theme Requests

A Theme in signed mode requires every serving URL to carry a signature. This page is the whole specification — enough to reimplement in any language.

Signing is opt-in. A new Theme is public, and a public Theme ignores a signature if one is present. Turn signing on in the portal, on the Theme’s Settings tab.

Keys

A Theme holds a set of signing keys. Each key is a pair:


Key id — `k_9fK2mQ`	Public. It travels in every URL as `?kid=`.
Secret — 32 random bytes, base64url	Shown once, when the key is created. Store it where you keep server-side secrets.

The secret never leaves your server. Livry does not return it from any API at any access level — the API returns key ids only. If you lose it, create a new key and delete the old one.A signature computed in the browser means shipping the secret to every user, which defeats the entire mechanism.

A Theme can hold several keys at once, which is what makes rotation possible without downtime.

The algorithm

canonical = path + "?kid=" + kid
s         = base64url( HMAC-SHA256( key = UTF-8(secret), message = UTF-8(canonical) ) )
url       = "https://cdn.livry.dev" + path + "?kid=" + kid + "&s=" + s

Where path is the URL path from the leading slash, with no host and no query string:

/{environmentID}/{themeID}/{variantID|-}/{latest|n}/{file}

Three details that matter

The key id is inside the signed message

?kid= is part of the canonical string, not just of the URL. A signature made with one key therefore cannot be replayed against another key’s id on the same path.

The canonical path is Livry's spelling, not the request's raw path

A URL with a doubled slash, a percent-encoded letter or a trailing dot is normalised before the signature is checked. You cannot sign one spelling and serve another.

There is no host in the signed message, and no expiry

No host, so the same signature keeps working if cdn.livry.dev moves behind a CDN.No expiry, deliberately. An expiring signature changes the URL on every mint, which would defeat an edge cache entirely — and caching is the whole premise of the serving path. Deleting a key is the revocation mechanism; see below.

Worked example

// server.ts — runs on your server, never in the browser.
import { createHmac } from "node:crypto";

const LIVRY_KEY_ID = "k_9fK2mQ";
const LIVRY_SECRET = process.env.LIVRY_SIGNING_SECRET!; // shown once, when the key was created

export const signLivryUrl = (path: string) => {
  const s = createHmac("sha256", LIVRY_SECRET)
    .update(`${path}?kid=${LIVRY_KEY_ID}`)
    .digest("base64url");

  return `https://cdn.livry.dev${path}?kid=${LIVRY_KEY_ID}&s=${s}`;
};

// const href = signLivryUrl("/nR7xL2vB:production/kQ3mW9rP/bV8nT4zC/latest/tokens.css");

import base64, hmac, os
from hashlib import sha256

KEY_ID = "k_9fK2mQ"
SECRET = os.environ["LIVRY_SIGNING_SECRET"]

def sign_livry_url(path: str) -> str:
    canonical = f"{path}?kid={KEY_ID}".encode()
    digest = hmac.new(SECRET.encode(), canonical, sha256).digest()
    s = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
    return f"https://cdn.livry.dev{path}?kid={KEY_ID}&s={s}"

using System.Buffers.Text;
using System.Security.Cryptography;
using System.Text;

const string keyID = "k_9fK2mQ";
var secret = Environment.GetEnvironmentVariable("LIVRY_SIGNING_SECRET")!;

string SignLivryUrl(string path)
{
    var canonical = $"{path}?kid={keyID}";
    var mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(canonical));
    return $"https://cdn.livry.dev{path}?kid={keyID}&s={Base64Url.EncodeToString(mac)}";
}

PATH_ONLY="/nR7xL2vB:production/kQ3mW9rP/bV8nT4zC/latest/tokens.css"
KID="k_9fK2mQ"

S=$(printf '%s?kid=%s' "$PATH_ONLY" "$KID" \
  | openssl dgst -sha256 -hmac "$LIVRY_SIGNING_SECRET" -binary \
  | openssl base64 -A | tr '+/' '-_' | tr -d '=')

echo "https://cdn.livry.dev${PATH_ONLY}?kid=${KID}&s=${S}"

base64url with no padding. - and _ rather than + and /, and trailing = stripped. Node’s "base64url" and .NET’s Base64Url do this for you; Python and shell need the transform shown above.

Where to sign

Where	When it fits
At build time	You pin a version and the brand is known at build. Cheapest — the URL is a constant.
In your server renderer	The brand depends on the request (hostname, tenant, session). Sign per render; it is one HMAC.
In a small backend endpoint	A SPA that discovers its brand at runtime. Return the signed URL, never the secret.

Because there is no expiry, a signed URL is stable — you can compute it once and cache it alongside anything else.

Verification, and what a failure looks like

A signed Theme answers 403 when the signature is missing, malformed, made with an unknown key, or simply wrong. It is one answer for all four, so a caller probing keys learns nothing about which key ids exist. The comparison is constant-time, over the decoded bytes.

Rotation

A Theme holds several keys at once, so rotation has no cutover:

Add a second key

Both are now valid. URLs signed with either are served.

Deploy your app signing with the new key

Existing URLs signed with the old one keep working.

Delete the old key

URLs signed with it start answering 403.

Deleting a key is the only revocation, and caches lag it. A signature has no expiry, so a URL signed with a deleted key can keep working from a cache that already held it.That window is bounded: a signed answer is never cached for more than 300 seconds, whatever your Environment’s cache lifetime says. Wait five minutes after deleting a key before assuming it is dead everywhere.

Signing is not an allowlist

A signature proves the URL was minted by someone holding your secret. It says nothing about where the request came from — anyone who obtains a signed URL can fetch it. If you also need to constrain who may fetch, that is a separate mechanism:

Access control

Origin allowlists, IP ranges, and what each one is actually worth.

Get started

Theming

Integration guides

Teams and access

Serving

Account and billing

Help

Signed URLs: Authenticating Livry Theme Requests

Keys

The algorithm

Three details that matter

Worked example

Where to sign

Verification, and what a failure looks like

Rotation

Signing is not an allowlist

Access control

​Keys

​The algorithm

​Three details that matter

​Worked example

​Where to sign

​Verification, and what a failure looks like

​Rotation

​Signing is not an allowlist

Access control

Keys

The algorithm

Three details that matter

Worked example

Where to sign

Verification, and what a failure looks like

Rotation

Signing is not an allowlist