API Keys

Create, manage, and use space-scoped API keys.

API keys provide space-scoped authentication for server-to-server integrations. They are the recommended authentication method for production backends.

Key Format

API keys use the sk_ prefix followed by a random string:

sk_a1b2c3d4e5f6g7h8i9j0...

Creating an API 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-backend" }'

Response

{
  "data": {
    "id": 1,
    "name": "production-backend",
    "key": "sk_a1b2c3d4...",
    "type": "space",
    "space_id": "01HQ...",
    "is_active": true,
    "last_used_at": null,
    "expires_at": null
  }
}

The full API key is only shown once at creation time. Store it securely. It cannot be retrieved later.

Using API Keys

As a Bearer Token

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

As a Query Parameter

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

Key Properties

Field	Description
`id`	Auto-incrementing ID
`name`	Descriptive name for identification
`key`	The API key string (`sk_` prefix)
`type`	`space` (space-scoped)
`space_id`	The space this key is scoped to
`is_active`	Whether the key is currently active
`last_used_at`	Timestamp of last usage
`expires_at`	Optional expiration date

Listing Keys

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

Revoking a Key

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

Revoked keys are immediately invalidated. Any requests using the revoked key will return 401.

Key Validation

An API key is valid when:

is_active is true
expires_at is null or in the future
The key exists in the database

Each successful use updates the last_used_at timestamp.

Scoping

API keys are scoped 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.

Best Practices

Name keys descriptively (e.g., production-backend, staging-server, mobile-app)
Create separate keys for different environments and services
Never expose keys in client-side code. Use signed URLs or unsigned uploads for client-side access
Revoke unused keys promptly
Monitor last_used_at to identify stale keys
Store keys securely in environment variables or secret management systems

PreviousSecurity Overview NextSigned URLs