Signed URLs & Sharing

Signed URLs & Sharing

Guide to generating secure, shareable download links for your R2 files.

Overview

Signed URLs allow you to share files with others without requiring them to log in or have direct access to your R2 buckets.

Key Benefits:

• ✅ No authentication required to download
• ✅ Tamper-proof signatures prevent unauthorized access
• ✅ Easy to share via email, chat, or messaging apps
• ✅ Links remain valid indefinitely
• ✅ Full control over which files are shared

How Signed URLs Work

Security Model

Signed URLs use HMAC-SHA256 signatures to prevent tampering:

URL: /api/files/bucket/download/file.pdf?ts=1234567890&sig=abc123

Components:
├── Path: /api/files/bucket/download/file.pdf
├── Timestamp: ts=1234567890 (ensures uniqueness)
└── Signature: sig=abc123 (validates authenticity)

Signature Validation

1. URL received - Someone clicks your shared link
2. Path extracted - Server extracts file path from URL
3. Signature recalculated - Server recalculates expected signature
4. Validation - Actual signature compared to expected signature
5. Download allowed - If signatures match, file is served

Tampering Prevention

If someone modifies the URL:

• Changing the file path breaks the signature
• Changing the timestamp breaks the signature
• The server rejects requests with invalid signatures
• Download is denied with 403 Forbidden

Generating Signed URLs

Via Web UI (Grid View)

The easiest way to generate and copy a signed URL:

1. Open a bucket in Grid View (default)
2. Hover your mouse over a file card
3. Click the 🔗 Link icon in the top-right corner
4. The signed URL is automatically copied to your clipboard
5. Paste it anywhere to share

Via Web UI (List View)

For List View display:

1. Switch to List View (click List icon in toolbar)
2. Find the file in the list
3. Click Copy Link button in the Actions column
4. The signed URL is automatically copied to your clipboard
5. Paste it anywhere to share

Via API

curl https://YOUR_DOMAIN/api/files/my-bucket/signed-url/myfile.pdf

Response:

{
  "success": true,
  "url": "https://your-domain.com/api/files/my-bucket/download/myfile.pdf?ts=1234567890&sig=abc123"
}

Via API (Encoded Filenames)

For files with special characters, URL-encode the filename:

curl https://YOUR_DOMAIN/api/files/my-bucket/signed-url/my%20file%20(v2).pdf

Sharing Signed URLs

Email

1. Generate signed URL
2. Include in email body:

   Click here to download: https://your-domain.com/api/files/...
   

3. Send to recipient
4. Recipient clicks link to download

Slack/Teams

1. Generate signed URL
2. Paste directly in message:

   @user here's the file you asked for: https://your-domain.com/api/files/...
   

3. Recipients can click link
4. No authentication required

In Documents

1. Generate signed URL
2. Add to documentation or README
3. Users can click link to download
4. Useful for sharing resources, datasets, manuals

In Public Websites

1. Generate signed URLs for files
2. Add links to your website
3. Visitors can download without logging in
4. Great for white papers, case studies, templates

URL Characteristics

Validity

• Duration: Links remain valid indefinitely
• Expiration: No automatic expiration
• Revocation: Delete the file to revoke access

Uniqueness

• Per-file: Each file gets unique signatures
• Timestamps: Include current timestamp for uniqueness
• Regeneration: Generating new URL creates different link (different timestamp, different signature)

Size

• Typical length: 100-150 characters
• Encoding: URL-safe characters only
• Compressible: Can be shortened with URL shorteners

Security Considerations

✅ Secure Practices

DO:

• Generate new URLs for each sharing scenario
• Review recipient list before sharing
• Use in secure communication channels (HTTPS)
• Monitor signed URLs in logs
• Delete files after sharing if temporary

Example - Secure Sharing:

1. Generate signed URL
2. Send via HTTPS (email, Slack, Teams)
3. Share with specific individuals
4. Delete file after deadline

❌ Risky Practices

DON'T:

• Share URLs in unencrypted channels (plain HTTP, unencrypted email)
• Post URLs in public forums or social media
• Share with broad audiences unless necessary
• Leave old signed URLs active indefinitely
• Share sensitive files without reviewing contents

Example - Risky Sharing:

❌ Post on public GitHub: https://your-domain.com/api/files/my-bucket/download/secret.pdf
❌ Post on public Slack channel with lots of viewers
❌ Leave URL in shared documents indefinitely

Common Use Cases

Sharing Documents

1. Upload report.pdf to bucket
2. Generate signed URL
3. Send to team members
4. They download and review
5. File remains in bucket for archive

Temporary File Sharing

1. Upload temp-data.csv to bucket
2. Generate signed URL
3. Share with external partner
4. Partner downloads file
5. Delete file after deadline
6. URL no longer works (file deleted)

Public Resource Distribution

1. Upload template.docx to bucket
2. Generate signed URL
3. Add to website/documentation
4. Thousands of users can download
5. All using same signed URL
6. No rate limiting concerns

API Access

1. Upload dataset.json to bucket
2. Generate signed URL
3. Use in API endpoint
4. Clients call: GET /api/download?file=dataset.json
5. Backend redirects to signed URL
6. Client downloads file

Troubleshooting

URL Not Working

Problem: "403 Forbidden" or "Invalid signature" error

Solutions:

1. Check URL wasn't modified
2. Verify file still exists in bucket
3. Check bucket name is correct
4. Try regenerating URL
5. Look for special characters in filename

URL Too Long

Problem: URL is very long, hard to share

Solutions:

1. Use URL shortener (bit.ly, tinyurl.com)
2. Embed in QR code
3. Put in button on website
4. Send as email attachment with link

Can't Copy URL

Problem: "Copy to clipboard" doesn't work

Solutions:

1. Check browser clipboard permissions
2. Try manual copy (Ctrl+C)
3. Try different browser
4. Check browser console for errors
5. Use API method instead

Recipient Can't Download

Problem: "File not found" or "404 error"

Solutions:

1. Verify file exists in bucket
2. Check bucket name is correct
3. Check file path in URL
4. Make sure sender didn't delete file
5. Try regenerating signed URL

API Reference

See the API Reference for complete documentation:

• Generate Signed URL
• Download File

---

Advanced Topics

Rate Limiting

Signed URLs respect R2's rate limits:

• Standard API limits apply
• No additional rate limiting per URL
• Safe to share widely

Bandwidth Costs

Downloads via signed URLs:

• Use standard egress pricing
• Benefit from Cloudflare's zero egress (free)
• Cost same as any other download method

Analytics

Track downloads via Worker logs:

• Enable logging to see download requests
• Monitor via Cloudflare dashboard
• Analyze patterns and usage

---

Next Steps:

• Learn about File Operations
• Explore the API Reference
• Check Troubleshooting if you encounter issues