Spaces

Create and manage spaces for multi-tenant asset organization.

Spaces are isolated containers for organizing assets. Each space has its own files, folders, upload configs, API keys, and access controls.

Creating a Space

curl -X POST https://api.tzzl.io/api/v1/spaces \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "My App" }'

Response

{
  "data": {
    "id": "01HQ...",
    "name": "My App",
    "handle": "a1b2c3",
    "enabled": true,
    "folder_mode": "dynamic"
  }
}

When a space is created:

A unique 6-character handle is auto-generated
A default "starter" upload config is created
The creator is assigned the owner role

Space Properties

Field	Description
`id`	ULID primary key
`name`	Unique space name
`handle`	6-char auto-generated identifier (used in CDN URLs)
`enabled`	Whether the space is active
`folder_mode`	Folder behavior (`dynamic` by default)
`custom_domain`	Optional custom CDN domain
`webhook_url`	Optional webhook endpoint
`access_control`	JSON access control defaults
`security`	JSON security settings (watermark, etc.)
`active_upload_config_id`	Default upload config ID

Listing Spaces

curl https://api.tzzl.io/api/v1/spaces \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Returns cursor-paginated results for all spaces the user has access to.

Get a Space

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

The detailed view includes access_control and security settings.

Update a Space

curl -X PUT https://api.tzzl.io/api/v1/spaces/SPACE_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "webhook_url": "https://your-app.com/webhooks"
  }'

Delete a Space

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

User Roles

Spaces support role-based access control with four levels:

Role	Level	Permissions
`viewer`	1	Read-only access to files
`user`	2	Upload and manage own files
`admin`	3	Manage all files, folders, configs
`owner`	4	Full control including space settings and API keys

Roles are hierarchical. An admin can do everything a user can, plus more.

Space Access Control

Set default access control for all files in the 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
    }
  }'

Space Security

Configure security settings like watermarking:

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
      }
    }
  }'

When watermarking is enabled, the CDN composites the watermark image onto every delivered image from the space.

API Keys

Generate space-scoped API keys:

# Create a key
curl -X POST https://api.tzzl.io/api/v1/spaces/SPACE_ID/api-keys \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "production" }'

# List keys
curl https://api.tzzl.io/api/v1/spaces/SPACE_ID/api-keys \
  -H "Authorization: Bearer sk_a1b2c3d4..."

# Revoke a key
curl -X DELETE https://api.tzzl.io/api/v1/spaces/SPACE_ID/api-keys/KEY_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Active Space

You can set an active space from the Tuzzle dashboard for convenience. The active space is used as the default context when no space is explicitly specified.

PreviousFolders NextTags