Authentication

Tuzzle uses space-scoped API keys for all programmatic access across both the Upload API and Admin API. You create and manage API keys from the Tuzzle dashboard.

API Keys

API keys are the primary authentication method for integrating with Tuzzle. Each key is scoped to a single space, uses the sk_ prefix, and works with both API tiers (Upload API and Admin API).

Creating an API Key

1. Sign in to the Tuzzle dashboard
2. Navigate to the space you want to integrate with
3. Go to Settings > API Keys
4. Click Create API Key and give it a descriptive name

Using API Keys

Include the key as a Bearer token in the Authorization header:

curl -X POST https://api.tzzl.io/api/v1/upload \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -F "[email protected]" \
  -F "space=a1b2c3"

Or pass it as a query parameter:

https://api.tzzl.io/api/v1/files?api_key=sk_a1b2c3d4...

Key Scoping

Each API key is bound to a single space. A key created for space a1b2c3 can only access resources within that space. To access multiple spaces, create separate keys for each.

Signed URLs

Signed URLs provide temporary, time-limited access to protected files. They use HMAC-SHA256 signatures to authenticate requests without exposing your API key.

Use signed URLs when you need to:

• Grant temporary access to private or authenticated files
• Allow client-side file uploads without exposing your API key
• Share protected assets with external users

Generating a Signed URL

curl -X POST https://api.tzzl.io/api/v1/files/FILE_ID/signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..."

The response includes a time-limited CDN URL with an HMAC-SHA256 signature. Default expiration is 1 hour.

Signed Uploads

Generate a signed upload URL for client-side uploads:

curl -X POST https://api.tzzl.io/api/v1/upload/generate-signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_config_id": "01HQ...",
    "expiration_minutes": 30
  }'

Unsigned Uploads

For use cases like user avatars or public file drops, you can allow uploads without any authentication. Configure an upload config with allow_unsigned: true and set referrer restrictions.

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

See Upload Configs for setup details.

Best Practices

1. Never expose API keys in client-side code. Use signed URLs or unsigned uploads for browser-based access.
2. Create separate keys per environment (e.g., production, staging, development).
3. Rotate keys periodically and revoke unused ones from the dashboard.
4. Use authenticated file access type for sensitive assets that require signed URLs on every request.
5. Store keys in environment variables or a secret management system.