Signed URLs

Signed URLs provide temporary, tamper-proof access to protected resources. They are used for both file delivery and file uploads.

How Signed URLs Work

A signed URL contains:

1. The original URL path and parameters
2. An expires parameter (Unix timestamp)
3. A signature parameter (HMAC-SHA256 hex digest)

https://cdn.tzzl.io/a1b2c3/image-01HQ...?expires=1700000000&signature=a1b2c3d4...

The signature is computed over the URL path and all query parameters (sorted alphabetically, excluding the signature itself) using a server-side secret.

Delivery Signed URLs

For files with private or authenticated access types, generate a signed delivery URL:

curl -X POST https://api.tzzl.io/api/v1/files/FILE_ID/signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..."

The returned URL includes a time-limited signature. Default expiration is 1 hour.

With Transformations

Transformation parameters must be specified when generating the signed URL, as they are included in the signature:

https://cdn.tzzl.io/a1b2c3/image-01HQ...?w=400&f=webp&expires=1700000000&signature=...

You cannot add or change transformation parameters after the URL is signed.

Upload Signed URLs

For client-side uploads without exposing API credentials:

curl -X POST https://api.tzzl.io/api/v1/upload/generate-signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_config_id": "01HQ...",
    "expiration_minutes": 30
  }'

The client then uploads the file using the signed URL without needing a Bearer token.

Signature Validation

The CDN validates signatures by:

1. Extracting the signature and expires parameters
2. Checking that the current time is before expires
3. Rebuilding the string to sign: {path}?{sorted_params_without_signature}
4. Computing the expected HMAC-SHA256 signature
5. Comparing the computed signature to the provided one

If any step fails, the CDN returns 403 Forbidden.

Security Properties

• Tamper-proof: Changing any parameter invalidates the signature
• Time-limited: Expired URLs are rejected even with valid signatures
• Non-transferable: The signature is tied to the exact URL path and parameters
• Server-side only: The signing key is never exposed to clients

When to Use Signed URLs

Best Practices

• Set short expiration times for sensitive content
• Generate signed URLs on demand, not in advance
• Never cache signed URLs on the client beyond their expiration
• Use authenticated file type when CDN caching of the content is not acceptable
• Use private file type when CDN caching is acceptable after initial authentication