Organizations and tenants

Your organization is your account. Your tenants are where agents run. A workspace is one organization plus one of its tenants, as seen by you. Everything you do with tanomis, the Console, or the Platform API happens inside one workspace.

At a glance

• An organization owns members, roles, invitations, and one or more tenants.
• A tenant is the runtime and data-isolation boundary: agents, versions, sessions, and files live in exactly one tenant and never cross it.
• A workspace is your view of one organization and one attached tenant, with the role and capabilities you hold there. You select it once; the server re-checks it on every request.

The three objects

Object	What it holds	What it is not
Organization	Members, roles, invitations, tenant attachments, the audit trail	A runtime boundary. Nothing executes “in” an organization.
Tenant	Enabled agents and versions, sessions, runs, files, connectors, policy ceilings	A customer account. A tenant belongs to exactly one organization.
Workspace	The pair you selected plus your effective role and capabilities	A third resource. It is a projection of the other two for one caller.

An organization owns one tenant per customer, and usually a sandbox tenant that serves no customer. Adding a tenant later does not change identities, credentials, or API contracts. One attachment can be marked as the organization’s default.

Roles and capabilities

Every member has one role in the organization. Roles map to a small, fixed set of capabilities.

Role	Reach	Capabilities
Owner	Every tenant in the organization	manage, deploy, run, view
Admin	Every tenant in the organization	manage, deploy, run, view
Developer	Only tenants named in an explicit grant	As granted, from deploy, run, view
Viewer	Only tenants named in an explicit grant	As granted, usually view

What the capabilities mean in practice:

• view inspects agents, versions, sessions, runs, and files in the tenant.
• run creates sessions and runs enabled agents.
• deploy deploys and changes agent versions and their enablement.
• manage governs connector configuration where that is separately enabled. It does not grant organization or tenant administration; membership and grants are owner and admin work.

A grant names a member and a tenant. Accepting an invitation automatically grants the organization’s default tenant; if the organization has no default, the new member needs a grant before they can select a workspace.

How access is decided

Access is never something a client asserts. On every request the server resolves:

1. Who you are from the access token.
2. Which organization you asked for, and that you are a member of it.
3. Which tenant you asked for, that it is attached to that organization, and that your role or a grant reaches it.
4. Whether the operation is within your capabilities there.

Naming an organization or tenant in a header or a CLI flag can only narrow what your token already allows. It cannot widen it, and it cannot reach a tenant you are not granted. Memberships and grants can change at any time; the server re-resolves them when each request arrives, so a revoked grant takes effect on the next call.

Selecting a workspace

Discovery returns only what you may select:

Terminal

tanomis workspace ls
tanomis workspace use northwind --tenant bluewater-bank
tanomis workspace show

workspace ls lists your organizations and the tenants each grants you, with each tenant’s state. Select a tenant whose state is ready; a tenant that is still being provisioned can be saved as a selection, but the server refuses tenant-scoped operations until it becomes ready.

Applications do the same discovery over HTTP with List workspaces, then send the organization and tenant as request headers. See Invoke from your application.

Organization automation

An organization also owns its automation clients. Each client reaches all active, ready tenants attached to that organization, including future tenants. Its permission profile restricts actions across that reach. Human tenant grants and machine permissions are separate: machines do not inherit a human workspace selection or use per-tenant grants. A signed-in owner or admin manages their lifecycle.

Where to go next

• Invite people and grant tenants: Organization members and access.
• Understand how agents and versions live inside a tenant: Agents and versions.
• Sign in and select a workspace from the CLI: Authenticate and select a workspace.