Presigned URLs Reference

Complete documentation of presigned URL generation and usage.

Overview

Upon successful upload, r2put automatically generates a presigned download URL. This URL provides immediate access to the uploaded file without additional authentication.

URL Properties

Expiration

• Duration: 3600 seconds (1 hour)
• Start Time: URL generation time
• Expiration: 1 hour from generation
• Format: S3-compatible presigning

Access

• Immediate: Can be used immediately after generation
• No Authentication: No additional authentication required
• Direct Access: Can be used in browsers or HTTP clients
• Public: URL provides public access (anyone with URL can access)

Format

• S3-Compatible: Uses S3-compatible presigning
• Query Parameters: Includes all necessary authentication parameters
• Full URL: Complete URL with all query parameters

Behavior

Automatic Generation

• Generated automatically on successful upload
• No configuration required
• Always included in successful uploads

Display

• Displayed in terminal UI output
• Shown after successful upload
• Format: Full URL with query parameters

Example Output

› OBJECT PATH: production-v4/data.bin
› DOWNLOAD URL:
https://production-v4.abc123.r2.cloudflarestorage.com/data.bin?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...

Usage

Direct Download

Use the presigned URL directly in browsers or HTTP clients:

# Copy URL from terminal output
curl "https://production-v4.abc123.r2.cloudflarestorage.com/data.bin?X-Amz-..."

In Scripts

Capture and use the presigned URL in scripts:

#!/bin/bash

# Upload file
r2put --file ./data.bin --bucket my-bucket > output.txt

# Extract presigned URL (example - actual parsing depends on output format)
URL=$(grep "DOWNLOAD URL:" output.txt | cut -d' ' -f3-)

# Use URL
echo "Download URL: $URL"

In Applications

Use presigned URLs in applications:

// Example: Use presigned URL in web application
const presignedUrl = "https://bucket.account.r2.cloudflarestorage.com/file?X-Amz-...";

// Download file
fetch(presignedUrl)
  .then(response => response.blob())
  .then(blob => {
    // Use blob
  });

Limitations

Expiration

• Fixed Duration: Always 3600 seconds (1 hour)
• No Extension: Cannot extend expiration
• No Refresh: No refresh mechanism
• New Upload Required: Must re-upload to generate new URL

Single Use

• No Revocation: Cannot revoke URL before expiration
• Public Access: Anyone with URL can access file
• No Access Control: No additional access control beyond URL possession

Generation Failures

• Service Issues: May fail if R2 service has issues
• Error Display: Tool displays error message
• Upload Status: Upload may have succeeded even if URL generation failed
• Exit Code: Exit code 1 on URL generation failure

Troubleshooting

Presigned URL Not Working

Symptoms:

• URL doesn't work when accessed
• 403 or 404 errors
• URL appears truncated

Resolution:

• Verify URL was copied completely (may be truncated in terminal)
• Check URL expiration (valid for 1 hour)
• Ensure URL includes all query parameters
• Verify R2 bucket and object are accessible
• Check URL format is correct

URL Expired

Symptoms:

• URL returns 403 Forbidden
• Error indicates expiration

Resolution:

• URL expires after 1 hour
• Generate new URL by re-uploading file
• Use R2 API directly to generate new presigned URL
• Implement URL refresh mechanism if needed

URL Generation Failed

Symptoms:

• No URL displayed after upload
• Error message about URL generation

Resolution:

• Check R2 service status
• Verify object was uploaded (check R2 dashboard or API)
• Retry upload to generate new URL
• Use R2 API directly to generate presigned URL

Best Practices

URL Security

• Share Carefully: Presigned URLs provide public access
• Time-Limited: URLs expire after 1 hour (automatic)
• No Revocation: Cannot revoke before expiration
• Use HTTPS: URLs use HTTPS for secure transfer

URL Management

• Capture Immediately: Capture URL from terminal output
• Store Securely: Store URLs securely if needed
• Monitor Expiration: Track URL expiration times
• Regenerate as Needed: Re-upload to generate new URLs

Alternative Approaches

For more control over presigned URLs:

• Use @cfkit/r2 directly to generate URLs with custom expiration
• Implement URL refresh mechanism
• Use R2 API for programmatic URL generation

Example: Generating Custom Presigned URLs

If you need presigned URLs with different expiration or more control:

import { R2 } from '@cfkit/r2';

const r2 = new R2({
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
});

// Generate presigned URL with custom expiration (e.g., 24 hours)
const url = await r2.getPresignedUrl({
  bucket: 'my-bucket',
  key: 'data.bin',
  expiresIn: 86400, // 24 hours in seconds
});

console.log(url);