---
type: operations
title: Tenant Management
description: Ongoing tenant operations including viewing receipts, managing users and agents, adjusting policies, and monitoring usage and costs via the admin UI.
tags: [tenant, admin-ui, receipts, policies, users, agents, metering]
verified:
  - by: openwiki/0.7.2
    at: 2026-10-14T20:42:32.326Z
---
# Tenant Management

Tenant management in the Company OS is performed through the admin UI, which provides tenant-scoped views for administrators to oversee their workspace. The admin UI enables viewing receipts (the basis for billing and auditing), managing users and agents, adjusting policies, and monitoring usage and costs.

## Admin UI Access and Scoping

The admin UI (`apps/admin`) is a tenant-scoped interface that only displays data belonging to the currently authenticated tenant. Access is controlled through:

- **Tenant-admin role**: Only users with the tenant-admin role can access the admin UI
- **TenantContext enforcement**: All data queries are scoped by the `TenantContext` Effect-service, ensuring administrators only see their tenant's data
- **Route protection**: UI routes require authentication and tenant-admin authorization

## Viewing Receipts

Receipts are the fundamental primitive for billing, auditing, and observability. The admin UI provides a receipts table that shows:

- **Correlation ID**: Links receipts to initiating tasks
- **Principal information**: Who initiated the action (user, agent, or factory)
- **Capability invoked**: Which capability was executed
- **Cost breakdown**: Model costs (`cost_model_cents`) and infrastructure costs (`cost_infra_cents`) in cents
- **Token usage**: Input and output tokens for LLM calls
- **Outcome**: Status of the action (pending, success, failed, denied, uncertain)
- **Langfuse trace ID**: For distributed tracing correlation
- **Timestamps**: When the action was created and settled

Receipts are grouped by tenant and only visible to tenant-admins of that tenant. Each atomic action through the OS generates exactly one Receipt, making them the immutable basis for billing and auditing.

## Managing Users and Agents

Tenant administrators can manage:

### Users
- View and invite users to the tenant workspace
- Assign roles that determine capabilities and data access
- Manage Better Auth sessions and channel identity mappings (WhatsApp, Teams, etc.)
- Review user activity through associated receipts

### Agents
- **Ops agents**: Handle ongoing operational tasks that require access to tenant data (e.g., publishing job postings, sending invoices)
- **Factory agents**: Create software and integrations without accessing tenant data
- Agent credentials management: Each agent possesses its own credentials and has a designated human accountable principal
- Agent-class restrictions: Factory agents are limited to capabilities with `target: dev-tooling` and cannot invoke tenant-app capabilities

## Adjusting Policies

Policies are encoded as data and evaluated before action execution. Administrators can configure:

- **Approval rules**: Define which actions require approval and by whom
- **Effect class limits**: Set boundaries for different types of side effects
- **Budget controls**: Establish spending limits for model usage and infrastructure
- **Validity periods**: Define when policies are active
- **Stop conditions**: Specify when automated actions should halt

Policies are scoped to tenant, agent, or capability levels and are evaluated through the OS harness before any capability invocation.

## Monitoring Usage and Costs

Usage and cost monitoring leverages the metering primitive built into every Receipt:

### Real-time Monitoring
- Current period usage tracked through Receipt aggregation
- Cost breakdown by model vs. infrastructure
- Token consumption trends
- Action success/failure rates

### Billing Foundation
- The Receipt primitive captures all cost dimensions required for billing
- Infrastructure costs estimated per action
- Model costs tracked via LiteLLM virtual keys per principal
- Usage data flows to rating/billing adapters (e.g., Moneybird integration)
- Admin subscription fees handled separately from usage-based fees

### Cost Attribution
- Every action is tagged with tenant ID and principal ID
- Enables per-user, per-agent, and per-capability cost breakdowns
- Supports showback/chargeback models within tenant organizations

## Security and Isolation Considerations

Tenant management operations are protected by the same isolation mechanisms that protect tenant data:

- **Row-Level Security**: All queries include mandatory `tenant_id` filtering
- **TenantContext enforcement**: Database connections are scoped to current tenant
- **Principal identity resolution**: Channel identifiers (WhatsApp, Teams, etc.) must be explicitly linked to principals by tenant-admins
- **Factory agent restrictions**: Factory principals cannot invoke tenant-app capabilities, enforced at the registry permission level
- **No implicit principal creation**: The OS never creates principals automatically; only tenant-admins can link channel identities

## Related Operations

- See [Logging and Observability](/logging) for how receipts integrate with evlog and Langfuse
- See [Admin UI](/systems/admin-ui) for details on the admin interface implementation
- See [Tenant Onboarding](/workflows/onboarding-tenant) for initial tenant setup procedures