Tenant Management

A tenant maps to one of your users. Tenantbox creates tenants automatically on first upload you never need to provision them in advance. Use the tenant API to query usage, set storage quotas, and list files.

What is a tenant?

When you upload a file and pass a tenant_id, Tenantbox creates a namespace for that user inside your project. All files uploaded for that tenant_id are isolated from other tenants, they can't access each other's files.

Auto-created

Tenants are created the first time you upload a file for a new tenant_id. No setup needed.

Fully isolated

Files are namespaced per tenant. One tenant cannot access another tenant's files.

Usage tracked

Storage used is tracked per tenant automatically. Query it anytime via the usage endpoint.

The tenant object

Field	Type	Description
`tenant_id`	string	The external_tenant_id you passed at upload time. This is your user's ID from your own database.
`email`	string \| null	Optional email address for the tenant. Set when creating via the dashboard.
`storage_used_bytes`	integer	Total bytes currently stored for this tenant across all files.
`storage_limit_bytes`	integer \| null	Storage quota in bytes. null means unlimited.
`total_files`	integer	Number of confirmed uploaded files for this tenant.

Get tenant usage

Fetch the current storage usage, file count, and quota for any tenant. Use this to build usage meters and quota warnings in your UI.

GET /api/storage/tenants/{tenant_id}/usage/

curl -X GET "https://api.tenantbox.dev/api/storage/tenants/user_123/usage/" \
  -H "Authorization: Bearer sk_live_xxx"

Sample response

{
  "tenant_id": "user_123",
  "email": null,
  "storage_used_bytes": 10485760,
  "storage_limit_bytes": 524288000,
  "total_files": 4
}

Set a storage limit

Set a per-tenant storage quota in bytes. When a tenant reaches their limit, any subsequent upload attempts will return a 413 error. Pass null to remove the limit entirely.

PATCH /api/storage/tenants/{tenant_id}/limit/

Request body

Field	Type	Description
`storage_limit_bytes`	integer \| null	Quota in bytes. Pass null to remove the limit. Example: 524288000 = 500MB.

Common storage sizes in bytes

100 MB	`104857600`
500 MB	`524288000`
1 GB	`1073741824`
5 GB	`5368709120`
10 GB	`10737418240`

# Set a 500MB storage limit
curl -X PATCH "https://api.tenantbox.dev/api/storage/tenants/user_123/limit/" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_limit_bytes": 524288000
  }'

# Remove the storage limit (set to null)
curl -X PATCH "https://api.tenantbox.dev/api/storage/tenants/user_123/limit/" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_limit_bytes": null
  }'

Sample response

{
  "tenant_id": "user_123",
  "storage_limit_bytes": 524288000,
  "detail": "Storage limit updated"
}

Quota enforcement

When a tenant has a storage limit set, Tenantbox checks the limit before issuing a presigned upload URL. If the upload would exceed the quota, the request is rejected before anything reaches Tenantbox storage.

413Quota exceeded — upload rejected

{
  "detail": "Storage quota exceeded for this tenant"
}

Handle this error in your application to show a meaningful message to your user — for example, prompting them to delete old files or upgrade their plan before uploading more.

Error responses

401Unauthorized

Invalid or missing API key.

{ "detail": "Unauthorized" }

404Not Found

No tenant exists with that external_tenant_id for this project.

{ "detail": "Tenant not found" }

Next - Storage quotas

Deep dive into quota strategies and best practices for managing tenant storage at scale.

Storage quotas