Unsigned Upload

Enable public uploads without authentication for widgets and UGC.

Unsigned uploads allow files to be uploaded without any authentication. This is useful for public upload widgets, user-generated content, and forms.

How It Works

Unsigned uploads use a special endpoint that accepts the space handle and upload config name in the URL path. No Bearer token is needed.

curl -X POST https://api.tzzl.io/api/v1/upload/unsigned/{spaceHandle}/{configName} \
  -F "[email protected]"

Example

curl -X POST https://api.tzzl.io/api/v1/upload/unsigned/a1b2c3/user-avatars \
  -F "[email protected]"

Requirements

The upload config must have allow_unsigned set to true and must include unsigned_restrictions:

{
  "allow_unsigned": true,
  "unsigned_restrictions": {
    "allowed_referrers": ["example.com", "*.example.com"],
    "require_https": true,
    "max_uploads_per_hour": 100
  }
}

Restriction Fields

Field	Required	Description
`allowed_referrers`	Yes	Array of allowed referrer domains (supports wildcards)
`require_https`	Yes	Whether to enforce HTTPS-only uploads
`max_uploads_per_hour`	No	Rate limit per hour (1-1000)

Referrer Validation

The API checks the Referer header against the allowed_referrers list. Domain patterns support wildcards:

example.com matches exactly example.com
*.example.com matches app.example.com, staging.example.com, etc.

Rate Limiting

Unsigned uploads have their own rate limiting, separate from authenticated uploads. You can further restrict the rate with max_uploads_per_hour in the config.

When to Use

Public file upload forms on your website
User avatar uploads
User-generated content submissions
Any scenario where requiring authentication is impractical

Security Considerations

Always set allowed_referrers to prevent abuse
Enable require_https in production
Set a reasonable max_uploads_per_hour limit
All validation rules from the upload config still apply (format, size, dimensions)
Dangerous file extensions are always blocked

PreviousSigned Upload NextPresigned URLs