Tenant Management

Tenants are the top-level organizational units in Housecarl AuthZ. Each tenant operates in complete isolation with its own domains, policies, and user associations.

Creating a Tenant

Any authenticated user can create a new tenant. This is a bootstrap operation that does not require any existing policy permissions.

Using housectl

For bootstrap operations, start with a non-tenant-scoped login. Once the user is associated with a tenant and tenant-scoped login works in your environment, you can log in again with --tenant <tenant-name> for tenant-local workflows.

housectl config login http://localhost:50051 admin
housectl admin create "My Company" "Production environment for My Company"

Using the gRPC API

rpc CreateTenant(CreateTenantRequest) returns (Tenant);

What Happens When You Create a Tenant

When you create a tenant, Housecarl automatically provisions everything you need to start working immediately. This happens atomically in a single transaction:

1. Tenant Record

The tenant is created with the name and description you provide. Tenant names must be globally unique across the system.

2. User Association

You (the creating user) are automatically associated with the new tenant. This allows you to select this tenant when logging in and perform operations within the tenant context.

3. Root Domain

A domain named root is automatically created. This domain:

• Serves as the primary domain for the tenant
• Cannot be renamed (enforced by the database)
• Is where tenant-level authorization policies live
• Is the default policy evaluation context

4. Starter Policies

Two policies are automatically created in the root domain:

Starter Policy

Grants you (the creating user) full access to all resources within the tenant:

This policy uses your UUID (not username), so renaming your user account will not affect your access.

Root Access Policy

Grants the system root user (from the platform root tenant) administrative access to this tenant. This enables:

• Platform-level administration
• Support operations
• System maintenance

Security Considerations

Initial Access

After creating a tenant, only you have access. Before inviting other users:

1. Review the starter policy and understand what it grants
2. Create more restrictive policies for other users
3. Consider creating role-based policies (admin, editor, viewer, etc.)

Policy Best Practices

• Use UUIDs in policies: The starter policy uses your UUID, not your username. This prevents policy bypass through username changes.
• Principle of least privilege: Create specific policies for other users rather than copying the starter policy.
• Separate domains: Consider creating sub-domains for different parts of your application with more specific policies.

Managing Tenant Users

Associating Users with a Tenant

Users must be associated with a tenant before they can operate within it:

housectl tenant associate-user <tenant-id> <username>

User Access Flow

1. User is created (or signs up)
2. User is associated with a tenant
3. Policies are created to grant the user appropriate permissions
4. User logs in and selects the tenant (or refreshes into tenant context after bootstrap login)
5. User's JWT includes the tenant context
6. Policy engine evaluates requests against tenant's domain policies

Listing and Managing Tenants

# List all tenants (admin operation)
housectl admin list tenants

# Get tenant details
housectl tenant get <tenant-id>

# Update tenant
housectl tenant update <tenant-id> --description "New description"

# Delete tenant (cascades to all associated resources)
housectl tenant delete <tenant-id>

Next Steps

• Policy Administration - Configure fine-grained access control
• Policy Cookbook - Common policy patterns and examples