kubbi Documentation
kubbi is a temporary, secure drop box for data. A producer creates a kubbi — a single payload or a multi-file package — gets back a claim URL, and shares that URL with a consumer. The consumer picks up everything when ready. Once claimed (or expired), the data is gone forever.
How it works
- A producer sends a payload (or a bundle of files) to kubbi with a TTL and optional retrieval limit.
- kubbi encrypts the payload (AES-256-GCM), stores it, and returns a claim URL.
- The producer passes only the claim URL to the consumer through whatever channel connects them.
- The consumer claims the payload using the URL. No API key or account needed.
- The payload is removed when it expires, reaches its retrieval limit, or is deleted by the producer.
Key behaviours
- ·Encrypted at rest — payloads are encrypted with AES-256-GCM before storage. The database never holds plaintext.
- ·TTL expiry — every kubbi auto-expires based on its TTL (1 minute minimum; maximum depends on your plan).
- ·Burn after read — set
max_retrievals: 1and the payload is wiped the moment it is claimed. - ·No consumer auth — the consumer only needs the claim URL. No API key, no account.
- ·Producer control — the producer can inspect metadata or delete a kubbi before it is claimed.
- ·Multi-file packages — bundle multiple files in a single kubbi. One claim URL delivers everything — config, data, instructions, and attachments together. File count and size limits depend on your plan.
Producers and consumers
kubbi has two roles. Either role can be filled by any kind of actor — a human, an AI agent, a script, or a service.
| Role | Auth | What they do |
|---|---|---|
| Producer | API key (Bearer token) | Creates a kubbi (single content or multi-file package), gets back a claim URL |
| Consumer | None — just the claim URL | Inspects and/or claims the payload |
Capability URL pattern
The model kubbi uses — create a resource, get back a capability URL, share only the URL — is a well-established security pattern. The sensitive data stays on a secure server; only a short-lived, unguessable reference to it travels across potentially untrusted channels.
Real-world examples of the same pattern:
- AWS S3 presigned URLs
- Google Drive / Dropbox share links
- Password reset emails
- Stripe payment links
- DocuSign / e-signature links
- Magic sign-in links (Notion, Slack, Linear)