Skip to main content

​
Tenants

A tenant represents an organization or group. Tenants contain users and can be granted permissions on datasets, which apply to all members. This enables organization-wide access control and simplifies permission management for teams.
Tenant-level permissions — When a tenant is granted a permission on a dataset, all users in that tenant automatically inherit that permission.

​
Tenant Concept

Tenants are created by users who become the tenant owner. The owner can add other users to the tenant. Users can belong to at most one tenant, but tenants can contain multiple users.

​
Tenant-Level Permissions

When a tenant is granted a permission on a dataset, all users in that tenant automatically inherit that permission. This happens through the permission checking mechanism: get_all_user_permission_datasets() unions the user’s direct permissions with their tenant’s permissions. Tenants start with zero permissions. You can leave the tenant principal empty and manage access purely through individual user permissions, or grant tenant-wide permissions for organization-wide resources.

​
Permission Inheritance

Tenant-level grants are blanket: once a dataset permission is assigned to the tenant principal, every user whose tenant_id matches inherits it. Users can also receive direct permissions that differ from the tenant defaults, giving you flexibility to customize access for specific users within the same tenant.
The Tenant model defines what gets stored in the SQL database. The tenants table contains:
  • id: Unique identifier (UUID primary key, references principals.id)
  • name: Human-readable name (unique)
  • owner_id: ID of the user who created the tenant
  • create_tenant(tenant_name, user_id): Creates a new tenant with the specified user as owner
  • add_user_to_tenant(user_id, tenant_id, owner_id): Adds an existing user to a tenant (owner only)
  • remove_user_from_tenant(user_id, tenant_id, owner_id): Removes a user from the tenant. Also strips them from all roles in the tenant and revokes their permissions on tenant datasets. The tenant owner cannot be removed. Exposed via DELETE /v1/permissions/tenants/{tenant_id}/users/{user_id}.
Tenant deletion is not yet supported. There is no delete_tenant API or function. As a workaround, depopulate the tenant by calling remove_user_from_tenant for every non-owner member, then stop using the tenant.
  • Users without a tenant exist but are isolated
  • API endpoints for tenant management

​
Tenant Management

Tenant owners can:
  • Add users to the tenant
  • Remove users from the tenant
  • Grant permissions to the tenant principal
  • Manage tenant-level access to datasets
  • Delete the tenant
Tenant deletion — Any authenticated user can delete a tenant. An active subscription is not required to perform this operation.

​
Use Cases

Tenants are ideal for:
  • Organization-wide access — Grant broad permissions to all team members
  • Department-level isolation — Keep different departments’ data separate
  • Project-based grouping — Organize users around specific projects or initiatives
  • Scalable permission management — Avoid granting individual permissions to many users

​
Data Isolation

Each tenant’s data is completely isolated:
  • Database separation — Each user’s data is stored in their own directory
  • Permission boundaries — Users can only access datasets they have permissions for
  • No cross-tenant access — Data from one tenant cannot be accessed by users from another tenant

​
Best Practices

  • Start with tenant-level permissions — Grant broad access at the tenant level
  • Refine with user permissions — Override tenant defaults for specific users when needed
  • Use roles for granular control — Create roles within tenants for more specific access patterns
  • Regular permission audits — Review and update permissions as team structure changes

Roles

Learn about role-based permissions within tenants

ACL

Understand how permissions are stored and checked