Skip to content
BoilStream

Share catalog access

concept
TL;DR

Sharing gives another authorized user access to an existing catalog without copying its data. The catalog UUID identifies the resource; a display name or local alias does not grant permission. Catalog modes are reader, writer and admin. Membership and grant changes can invalidate access already held by a client.

Decision flowA shared catalog still checks each user’s permissions
A shared catalog still checks each user’s permissionsTwo users can refer to the same physical catalog. A request reaches a catalog permission check; an allowed action accesses the shared data, while a denied action fails without granting access.Catalog ownerGrants selectedpermissionsInvited userOwn identity andcredentialsAction allowed?Shared catalogSame physical dataPermission deniedNo access for this actionGrant accessRequest actionYesNoA shared catalog still checks each user’s permissionsTwo users can refer to the same physical catalog. A request reaches a catalog permission check; an allowed action accesses the shared data, while a denied action fails without granting access.Catalog ownerGrants selectedpermissionsInvited userOwn identity andcredentialsAction allowed?Shared catalogSame physical dataPermission deniedNo access for thisactionGrant accessRequest actionYesNo
Display names identify a catalog in a user’s context; sharing does not create a second copy of the data.

BoilStream isolates each tenant by default and permits access across tenants only through an explicit membership or catalog grant.

Isolation by default

Section titled “Isolation by default”

Each tenant has its own:

  • managed DuckLake catalogs, including tenant-specific duckie and boil__stream defaults when automatic provisioning is enabled;
  • encrypted non-catalog secrets;
  • server-side filesystem scope; and
  • authenticated sessions and resource limits.

Two tenants may use the same catalog display name without referring to the same catalog. The canonical catalog UUID, not the display name, identifies the authorization and storage target.

Sharing one catalog

Section titled “Sharing one catalog”

Sharing reuses the owner’s catalog. It does not copy data into the requester’s tenant or create a second physical catalog.

Concept Meaning
Requester The authenticated user whose access is checked and audited
Storage owner The tenant that owns the catalog and its data
Catalog UUID The authoritative identity selected for the operation
Display name A tenant-visible presentation name that may be reused elsewhere
Access mode The operations allowed for this requester on this catalog

The requester cannot change the storage owner by choosing a different SQL alias, database name, or same-named local catalog.

How access is obtained

Section titled “How access is obtained”

Catalog access may come from:

  • ownership, which provides administrative catalog access;
  • active tenant membership, which currently provides admin access to catalogs owned by that tenant; or
  • a direct catalog grant, which carries an explicit mode and may expire.

Removing membership or revoking, reducing or expiring a grant can invalidate existing access. Applications must handle authorization failures and request fresh credentials when authorized; a previously issued credential does not preserve a revoked grant.

Catalog access modes

Section titled “Catalog access modes”

Catalog modes are intentionally separate from product roles:

Mode Data reads Data mutations Catalog DDL
reader yes no no
writer yes yes no
admin yes yes yes

Catalog ownership, membership, and grant lifecycle remain BoilStream control-plane operations; the admin data-plane mode does not let a SQL statement rewrite those relationships.

Product roles and catalog access modes serve different purposes. Check the user’s catalog permissions when an operation is denied; a successful web login alone does not grant access to every catalog.

Grant and revoke access

Section titled “Grant and revoke access”

Direct-grant administration requires a superadmin session with verified MFA. The grantee must be an active account. Use the catalog UUID returned by discovery; a user’s chosen SQL alias is not the target.

Method Path Action
GET /auth/api/admin/ducklakes/{catalog_id}/grants Inspect grant history for the catalog.
POST /auth/api/admin/ducklakes/{catalog_id}/grants Create or replace the user’s direct grant.
DELETE /auth/api/admin/ducklakes/{catalog_id}/grants/{grantee_email} Revoke the user’s active direct grant.

For POST, send JSON with an explicit mode:

JSON
{
  "grantee_email": "analyst@example.com",
  "access_mode": "reader",
  "expires_at": null
}

expires_at may instead be a UTC timestamp. A successful create returns HTTP 201 with grant_id, catalog_id, grantee_email, access_mode and expires_at. Invalid input is rejected; an absent or inactive grantee cannot receive the grant. URL-encode the email when using DELETE. Successful revocation returns HTTP 200 with {"ok":true}.

Verify with the grantee’s own session: discover the catalog, attach it with native DuckDB, read a known row, and confirm that reader access denies writes. After revocation, verify that access is denied. Membership may independently grant access, so revoking a direct grant does not remove membership-derived permissions.

If an operation fails or the response is lost, list the grant state before repeating it. Do not infer the effective access mode from a successful administrator login.

Other tenant-scoped resources

Section titled “Other tenant-scoped resources”

Non-catalog secrets remain encrypted and scoped to the authenticated tenant. Server-side filesystem access is confined below the configured tenant data base path. Session and connection limits are deployment settings; use the generated configuration reference rather than copying partial security configuration.

Section titled “Related guides”