---
title: Organizations and workspaces
description: The two scopes everything in Subako belongs to — who is billed, and where the work lives.
sidebar:
  order: 1
---

Subako has exactly two scopes, and every resource sits in one of them.

An **organization** is the identity and billing boundary. It owns a handle, a set of members, a [plan, and a credit balance](/concepts/plans-and-billing). A credential authenticates for exactly one organization, which is why no command takes an organization name: the profile you are acting as already decides.

A **workspace** is where work lives. Agents, skills, vaults, model providers, API keys, and sessions all belong to one, and nothing crosses between them. Most teams run one workspace per environment — `staging`, `production` — or one per product surface.

## Roles

Membership carries a role at each scope, and the two are independent: being an organization admin does not put you in a workspace.

| Role | In an organization | In a workspace |
| --- | --- | --- |
| `admin` | Manages members, invitations, billing, and workspaces | Manages members and API keys, plus everything a member can do |
| `member` | Belongs to the organization; reaches the workspaces they are added to | Reads and runs the workspace's resources |

The last admin of an organization cannot be demoted.

## Joining

There is no invitation link to pass around. You invite an address, and that address joins by signing in through the organization's identity provider:

```bash
subako org invite --email dev@acme.example --role member
subako org invitations
```

An invitation that has not been accepted can be revoked; one already accepted is a membership, and you remove the member instead.

```bash
subako org members
subako org set-role <user-id> --role admin
subako org remove-member <user-id>
```

Removing a member drops their workspace memberships in that organization too. API keys they minted are left alone — a key is the workspace's machine credential, not a delegation of the person who created it.

## Selecting a workspace

The CLI records the selected workspace in your credential profile, so ordinary commands carry no workspace flag:

```bash
subako workspace list      # * marks the selected one
subako workspace use production
```

Adding someone to a workspace requires them to be an organization member already:

```bash
subako workspace add-member <user-id> --role member
subako workspace members
```

## Profiles

One machine often needs several logins — two organizations, or a staging and a production server. Each `subako login` stores a **profile**, and commands act as the current one unless `--profile` says otherwise.

```bash
subako profile list
subako profile use staging
```

Credentials live in `~/.config/subako/credentials.json`, or wherever `SUBAKO_CREDENTIALS_FILE` points. `--credentials-file` overrides both, which is the hook for CI.

:::note
Because a profile carries the server, the organization, and the selected workspace, switching profiles switches all three at once.
:::