# Organizations and tenants

How a customer organization, its members and roles, its runtime tenants, and the workspace you select fit together.

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.

- 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:

```bash title="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](/api/workspaces/list-workspaces), then send the organization and tenant as
request headers. See [Invoke from your application](/guides/run/invoke-from-your-application).

## Organization automation

An organization also owns its [automation clients](/guides/deploy/automation-credentials).
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](/guides/manage/organization-members).
- Understand how agents and versions live inside a tenant: [Agents and versions](/concepts/agents-and-versions).
- Sign in and select a workspace from the CLI: [Authenticate and select a workspace](/getting-started/authenticate-and-select-workspace).