> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations and teams

> Create an org, invite people, set their roles, and group them into teams. From the console, the CLI, or the SDKs.

Every account works inside an organization, and your personal account counts as one. An org is where machines are billed, where sharing happens, and where secrets live. This page is about the org itself: its members, their roles, and the teams inside it. For what sharing does to a machine, see [VM sharing](/guides/share-a-vm).

Everything here is available from the console's **Organization** page, from `boxd auth org` and `boxd teams` on the CLI, and from the SDKs' `orgs` and `teams` namespaces.

## Roles

| Role | Can |
| - | - |
| **member** | use the org's shared machines, create org-billed machines, read the org's settings |
| **admin** | everything a member can, plus invite and remove members, change roles, rename the org, set org-wide defaults, create teams |
| **owner** | everything an admin can, plus demote other admins. There is one owner, and ownership is transferred by the boxd team on request |

## Create an org and manage its roster

```bash theme={"theme":"github-dark"}
boxd auth org new "Acme"                        # you become owner and admin; the CLI switches to it
boxd auth org rename "Acme Labs"                # admin only
boxd auth org members                           # roster, plus pending invites for admins (alias: ls)
boxd auth org invite dev@example.com --role member   # admin only; emails the link and prints it too
boxd auth org revoke-invite <token>             # admin only
boxd auth org remove-member <user_id> -y        # admin only; plain members only
boxd auth org set-role <user_id> admin          # promote; `member` demotes
```

A few rules keep the org safe from its own credentials:

* **Invites carry a role.** The invitee lands as `member` or `admin`, and an admin invite can only be sent from an interactive login. An API key or a token minted inside a machine cannot send one, and cannot read the links of pending invites either. It still sees that an invite is pending.
* **Demoting another admin is owner-only.** An admin can always demote themselves.
* **The owner's role cannot be changed** with `set-role`, and an owner or admin cannot be removed with `remove-member`. Both go through the boxd team.
* **A member who still owns org-billed machines cannot be removed.** Move those machines to personal billing or destroy them first.

Every one of these commands follows the active org context, so `boxd auth switch acme` first, or pass `--org acme` for one call.

## Teams

A team is a group of members inside an org, with an optional default snapshot. A machine created by a team member boots from that snapshot unless they pick another one, which is how a team hands every new machine the same starting point. See [Golden image](/guides/golden-image).

```bash theme={"theme":"github-dark"}
boxd teams new backend                          # org admin only
boxd teams list                                 # every team for an admin; your own teams otherwise (alias: ls)
boxd teams get backend                          # roster and default snapshot
boxd teams add-member backend <user_id>         # team admin only; must already be an org member
boxd teams remove-member backend <user_id>
boxd teams set-role backend <user_id> admin
boxd teams set-default-snapshot backend golden  # must be a shared snapshot
boxd teams set-default-snapshot backend --clear
boxd teams rename backend platform
boxd teams destroy backend -y                   # alias: rm
```

An org admin has team-admin authority on every team. A team admin has it on their own team.

## From the SDKs

```python theme={"theme":"github-dark"}
org = boxd.orgs.create("Acme")
boxd.orgs.get_members("acme")                       # OrgMembers(members, invites)
boxd.orgs.invite("dev@example.com", role="member", org="acme")
boxd.orgs.set_member_role("usr_...", "admin", org="acme")
boxd.orgs.remove_member("usr_...", org="acme")

team = boxd.teams.create("backend", org="acme")
boxd.teams.add_member(team.id, "usr_...")
boxd.teams.set_default_snapshot(team.id, snapshot.id)
```

```typescript theme={"theme":"github-dark"}
const org = await boxd.orgs.create("Acme");
await boxd.orgs.getMembers("acme");                 // { members, invites }
await boxd.orgs.invite("dev@example.com", { role: "member", org: "acme" });
await boxd.orgs.setMemberRole("usr_...", "admin", "acme");
await boxd.orgs.removeMember("usr_...", "acme");

const team = await boxd.teams.create("backend", "acme");
await boxd.teams.addMember(team.id, "usr_...");
await boxd.teams.setDefaultSnapshot(team.id, snapshot.id);
```

See [Organizations](/reference/python-sdk#organizations) and [Teams](/reference/python-sdk#teams) in the Python reference, and the same sections in the [TypeScript reference](/reference/typescript-sdk#organizations).

## Live everywhere

A change made on one surface shows up on the others without a reload. Invite someone from the CLI and the console's Organization page lists the invite as it lands. The same goes for role changes, team rosters, and every machine setting.