Organizations and teams

An organization owns a membership directory, governance settings and a prepaid wallet. A team groups people within one organization, and teams can be arranged in a structure: a team may sit under another team, up to five levels deep, so an organization can model Organization → Department → Sub-department → Team → Member or any shallower shape. A person can belong to several organizations and teams; those memberships do not combine their wallets or authority.

Create an organization

1. Open the organization selector and choose Create organization. It is also available from Ctrl+K or Command+K.
2. Enter an Organization name your team will recognize, then select Create organization.
3. The page creates the organization and opens its Home page. You become its owner; invite members, create API keys, and configure credit and usage limits after creation.
4. If the organization is created but opening it fails, select Retry switch. This opens the existing organization without creating another one.

A personal account uses the same organization billing machinery. A shared organization's settings and credit are separate from a person's other workspaces.

Invite people

As an organization administrator, open People and choose Invitations. Enter the recipient's email, choose an available fixed role and optionally select teams. Review the organization and team names before sending.

Email delivery requires the deployment's SMTP configuration. A failed email does not delete the invitation: inspect its delivery status and use Retry delivery when available. Pending invitations can have their team selection updated before acceptance. Delivery retry uses the existing invitation rather than granting access twice.

The recipient signs in using the invited email, reviews the organization and teams, accepts, then opens the organization. If membership synchronization is still finishing, retry opening it. Expired, revoked or wrong-recipient links do not grant access; ask an administrator for a replacement when needed. A completed invitation does not restore memberships that were subsequently removed.

Create and manage teams

Open People. Teams is the first tab. The Structure view shows the organization's teams as a tree: expand a node with its + button to see its sub-teams and then its own roster (Load more appears for large teams), or open the team name for details. Flat list shows every team in one sortable table with its type and path. With organization usage permission, Share of organization cost and Cost per team over time chart the selected period above the table; the share includes usage from keys with no team, so its slices add up to the organization total, and an expanded team shows its own split by member.

Select New team to create one. Give it a clear name and choose a type, a parent and an owner (a description is optional). Then expand the team to manage its roster: Add an organization member as Administrator or Member, change a member's role, Move to… another team (their role goes with them), or remove them from the team (they stay in the organization). With a mouse you can also drag a member's grip onto another team's row. The team owner's row is fixed; ownership changes only through Transfer ownership in the team's Settings. For someone who has not joined the organization yet, use an invitation with team selection.

Types

Every team carries a type: Department, Sub-department or Team by default, and an administrator can add the organization's own labels under a team's Settings → Team kinds. A type is a label. It decides the badge on People and the label in the API-key team picker, nothing else: any type may sit at any level, hold direct members and hold sub-teams. Changing a team's type keeps its sub-teams, its people and its budgets.

Structure

A team's parent decides whose totals it counts toward. On the People page a department's Total · incl. sub-teams is the sum of its own attributed usage and every team beneath it; Direct is its own attribution alone. Names are unique among siblings, so Infra may exist under two departments; the path (engineering/platform/infra) tells them apart in the API-key picker and the CLI.

Move a team from its Settings page or the row menu. The whole subtree moves with it. A team cannot be moved under one of its own sub-teams, and the structure cannot exceed five levels. Moving changes what the team's usage rolls into from the next read on; nothing about its API keys, roster or history changes. A team with sub-teams cannot be deleted or archived until they are moved or deleted; the delete dialog lists what would be affected.

Members of a sub-team are not direct members of its parent. A parent's Members card can show them ("including sub-teams") with the team they came through; add someone directly to a department to give them a role on that node.

Directory visibility is not management authority. Members can read permitted rosters; administrator actions remain permission-gated. The last owner cannot simply be removed or demoted. Arrange an ownership transfer or another eligible owner first.

Attribute requests to a team

Joining a team alone does not assign every personal request to that team. A personal API key reports against the team chosen when it is created, from your teams in the key's billing organization. With one team it is selected for you; with several, Create API key waits until you pick one or choose No team attribution; with none, the key has no team. The picker groups teams by department and shows each team's path. Any team you are a direct member of can be chosen, a department included. From the CLI, tokamak auth --team <id> preselects a team by its numeric id on the browser approval page, where you can also choose it; tokamak auth-token --team engineering/platform accepts a path, a unique name or the numeric id. The key keeps that attribution and its billing organization. To change them, revoke and replace the key. The key list names each key's team; a key created before the team question shows its team as derived from your current membership, and its requests follow the team you belong to until you replace it. An optional agent type on the key (Claude Code, Codex, OpenCode or a Custom name) is different: it only labels which tool calls the API for the Agents page, the key's owner can change it later, and a change applies to future requests.

Auth checks live team authority for team-attributed keys. After membership removal reaches auth, the key is refused rather than silently sending unassigned traffic. Service-account credentials have a separate ownership model; do not treat their team binding as a personal-key preference.

See Access control, Budgets and limits and Customer FAQ.