Concepts in plain words

The docs lean on a small set of terms. Here is what each one means, in plain words, with a link to the page that goes deeper. Skim this once and the rest of the docs read faster.

Tenant

One customer, workspace, or project in your app. Every bucket and key belongs to exactly one tenant, and a tenant can never see another tenant's data. When the docs say "org", they mean the tenant.

Deeper: Tenancy & auth.

Access key

The long-lived credential a server holds: an id plus a secret. The secret is shown once at creation and never again, so your app stores it in its own database.

Scoped key

An access key restricted to what it may do: which operations (read, write, delete), and optionally one bucket or key prefix. A leaked read-only key cannot write; a key scoped to one bucket cannot touch another. Scoping is how you give each part of your system the least access it needs.

Deeper: scoped access keys.

Surface

One of the three ways to talk to the same server: the S3 API (for existing S3 tools), the native API (JSON, made for app code), and the admin API (management). They are different doors into one building; the security checks inside are identical.

Deeper: The three surfaces.

Bearer token

A short-lived pass the native client mints from your access key and sends on each request. You never handle it: the SDK mints, caches, and refreshes it for you. If the underlying key is revoked, the token stops working too.

Admin token

A separate credential (lwadm_...) for the management API: creating tenants, minting keys, setting quotas, reading audit logs. It lives on your server, never in a browser, and carries a role (owner, operator, or viewer).

Deeper: Admin API.

Signed URL

A link that grants one action on one object for a few minutes, with the authorization baked into the URL itself. Your server mints it; the browser uses it with no credential. This is how browsers upload and download directly without your app proxying the bytes.

Deeper: Signed URLs.

The app kit

LockwellKit, a helper that composes the admin and native clients into the four jobs every multi-tenant app needs: provision a tenant, get a per-tenant client, sign browser URLs, and verify webhooks. It is convenience only; it adds no new server behavior.

Deeper: The app kit.

Bucket, object, version

Same meaning as S3. A bucket is a named container inside a tenant. An object is a file plus its metadata, addressed by a key like invoices/2026/03.pdf. With versioning on, every write keeps the previous version instead of overwriting it.

Deeper: Upload & download and Versioning.

Idempotency key

A label you attach to a write so that retrying the same request applies it once instead of twice. Pair it with a checksum on the native API.

Deeper: Conditional writes & idempotency.

Webhook

An HTTP POST Lockwell sends to your endpoint when an object is created or removed, signed so you can verify it really came from your server.

Deeper: Webhooks.