Skip to main content

What tenants are

A tenant represents an organization or workspace that shares one theAuth deployment. The tenant module stores tenant records (name, slug, settings, status), and agents and budget policies can carry a tenantId.
Tenants are a data model, not an enforcement layer. What exists today: agent.create({ tenantId }) stores the tenant on the agent, and agent.list({ tenantId }) filters by it. Nothing else reads it: authorize() does not compare tenants, a suspended tenant does not block authorization, the settings values are not applied when agents or delegations are created, and the audit log and REST endpoints have no tenant filter. If you need isolation, enforce it in your own code, for example by checking agent.tenantId against the caller’s tenant before acting.
tenantId is nullable everywhere it appears. Existing agents, policies, and audit entries created before you start using tenants continue to work without modification.

Data model

string
Stable identifier with a tnt_ prefix, e.g. tnt_acme.
string
Display name for the tenant.
string
URL-safe identifier. Lowercase letters, numbers, and hyphens only. Must be unique.
TenantSettings
Per-tenant configuration values, stored on the tenant record and not enforced by the SDK (see the note above).
'active' | 'suspended'
Recorded by suspend() and activate(). The SDK does not currently act on it.
Date
When the tenant was created.
Date
When the tenant was last modified.

TenantSettings

number
default:"undefined (uses global limit)"
Intended cap on active agents in this tenant. Not enforced; the cap that applies is agents.maxPerUser.
number
default:"undefined"
Intended delegation depth limit. Not enforced; delegation uses the maxDepth passed to delegate().
number
default:"undefined (no automatic pruning)"
Intended audit retention for this tenant, in days. Not enforced; call theauth.audit.cleanup({ retentionDays }) yourself.
string[]
default:"undefined (all types allowed)"
Intended restriction on agent types. Not enforced.

Creating a tenant

Slugs must be unique and match ^[a-z0-9]+(?:-[a-z0-9]+)*$. theAuth rejects duplicate slugs at creation time.

Creating an agent inside a tenant

Pass tenantId when creating an agent with theauth.agent.create. The agent stores that tenant ID, and the tenant must already exist (foreign key). The REST endpoint POST /agents ignores tenantId.

Listing agents by tenant

Available on theauth.agent.list only; GET /agents has no tenantId parameter.

Fetching and updating a tenant

Settings are merged, not replaced. Fields you omit in the update keep their existing values.

Listing all tenants

Useful for admin dashboards. Returns all tenants regardless of status.

Suspending and reactivating

suspend and activate flip the tenant’s status between suspended and active. The SDK does not check that status when authorizing, so suspending a tenant does not stop its agents by itself. To cut off a tenant today, check tenant.status in your own code, or revoke its agents with theauth.agent.revoke.

Budget policies per tenant

Budget policies store a tenantId, but checkBudget and recordUsage match policies by agentId only, so a tenant-only policy applies to every agent, not just the tenant’s. See Budget policies for the full reference and how to enforce limits.

Next steps

Budget policies

Per-agent and global cost limits, with the check and enforcement steps you call yourself.

Agent identity

Create agents scoped to a tenant.

Audit log

Query the audit trail by agent or user.
Last modified on October 7, 2026