Access Control

Tuzzle provides a hierarchical access control system that cascades from spaces to folders to files.

Three Access Levels

Inheritance Hierarchy

Access control settings cascade downward:

Space → Folder → File

A file's access control includes an inherited_from field that shows where the setting came from:

{
  "requires_auth": true,
  "source": "folder",
  "inherited_from": "01HQ..."
}

Source Values

Space-Level Access Control

Set default access control for all files in a space:

curl -X PUT https://api.tzzl.io/api/v1/spaces/SPACE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "access_control": {
      "requires_auth": true,
      "public_read": false
    }
  }'

Reset to defaults:

curl -X DELETE https://api.tzzl.io/api/v1/spaces/SPACE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Folder-Level Access Control

Override access control for a specific folder and its contents:

curl -X PUT https://api.tzzl.io/api/v1/folders/FOLDER_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "access_control": {
      "requires_auth": true
    }
  }'

File-Level Access Control

Override access control for a specific file:

curl -X PUT https://api.tzzl.io/api/v1/files/FILE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "access_control": {
      "requires_auth": false
    }
  }'

Space Security Settings

Spaces also have a separate security configuration for additional protections:

curl -X PUT https://api.tzzl.io/api/v1/spaces/SPACE_ID/security \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "security": {
      "watermark": {
        "enabled": true,
        "url": "https://example.com/watermark.png",
        "position": "southeast",
        "opacity": 0.5
      }
    }
  }'

CDN Enforcement

The CDN enforces access control on every request:

1. Fetches the file's access control settings from the API
2. For private and authenticated files, requires a valid signed URL
3. Rejects requests with invalid or expired signatures (403)
4. For authenticated files, disables CDN caching

Best Practices

• Use upload type for public assets (marketing images, product photos)
• Use private type for user-uploaded content that needs controlled sharing
• Use authenticated type for sensitive documents that should never be cached
• Set access control at the space or folder level to avoid managing individual files
• Use upload configs to automatically apply the right access type on upload