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

# Accounts, organizations and workspaces

> How your Mutagent account is organized, which workspace a command runs in, and how to switch.

You sign in once per organization. After that, every `mutagent` command runs in one workspace of that
organization, and you choose which one.

```mermaid theme={null}
flowchart TB
  U["You<br/>(one account)"] --> O1["Organization: acme"]
  U --> O2["Organization: side-project"]
  O1 --> W1["Workspace: support-bots"]
  O1 --> W2["Workspace: sales-agents"]
  O2 --> W3["Workspace: Default workspace"]
  W1 --- R1["LLM providers · Environments<br/>managed agents · members · API keys"]
```

| Level | What it holds | Where you manage it |
| - | - | - |
| **Account** | Your sign-in and profile. One account can belong to several organizations. | app.mutagent.io › Settings › Profile |
| **Organization** | Members, invitations, organization API keys, and its workspaces. | app.mutagent.io › Settings › Organization |
| **Workspace** | The things your agents use: LLM providers, Environments, managed agents, and workspace API keys. Two workspaces never see each other's LLM providers or Environments. | app.mutagent.io › Settings › Workspace (members, API keys), and app.mutagent.io › Configuration (LLM providers, Environments, integrations) |

When you sign up at [app.mutagent.io](https://app.mutagent.io), you name your organization, and
Mutagent creates a workspace in it named **Default workspace**. If your first sign-in is
`mutagent login` instead, the organization is named **Default** and the workspace **Default
workspace**. You can rename both, create more workspaces, and invite members in the web app.

## Sign in

```bash theme={null}
mutagent login
```

The browser approval page shows the organization and workspace you are signing in to. The key the CLI
stores is an **organization key**: it works in every workspace you are a member of in that
organization, for 30 days. The workspace you approved is selected.

To sign in to another organization, name it. The approval page preselects it:

```bash theme={null}
mutagent login --org side-project
```

The CLI holds one sign-in at a time; signing in to another organization replaces the stored key.

<Tip>
  **For coding agents.** With a key in `MUTAGENT_API_KEY`, run `mutagent login --json`: no browser.
  Without a key, run `mutagent login --browser --json`, show the printed URL to the user, and wait. The
  CLI never opens a browser under `--json`; it waits up to 5 minutes for the user to approve. See
  [mutagent login](/cli/commands/login).
</Tip>

## See where you are

```bash theme={null}
mutagent workspaces current
```

```text Output theme={null}
ℹ Key scope: organization
ℹ Organization: acme (org_Q7mZ2pLx9TnB4vKc_R8wd)
ℹ Workspace: support-bots (3f6a2c1e-8b4d-4e0a-9c7f-2d5e8a1b6c90)
ℹ Key expires: 2026-10-25T15:51:27.381Z
```

`Key scope` is `organization` for a key from `mutagent login` or from the organization API keys page,
and `workspace` for a workspace API key. See [API keys](/quickstart/api-keys).

`mutagent workspaces current --json` returns `scope`, `organization`, `workspace` and `expiresAt`. It
asks the server, so exit code 0 means the key works in that workspace. Exit code 2 means the key
expired or is invalid; exit code 3 means you are not signed in or no workspace is selected.

## Work in two workspaces

List the workspaces your key can use. `*` marks the selected one:

```bash theme={null}
mutagent workspaces list
```

```text Output theme={null}
SELECTED  ID                                    NAME           SLUG           URL
--------  ------------------------------------  -------------  -------------  --------------------------------------------------
*         3f6a2c1e-8b4d-4e0a-9c7f-2d5e8a1b6c90  support-bots   support-bots   https://app.mutagent.io/settings/workspace/general
          b81d7e40-15c9-4a3f-8e62-0f9c4d2a7b13  sales-agents   sales-agents   https://app.mutagent.io/settings/workspace/general

2 result(s)
```

Switch every later command to `sales-agents`. No browser and no prompt:

```bash theme={null}
mutagent workspaces use sales-agents
mutagent providers list        # the LLM providers stored in sales-agents
```

Run one command in the other workspace without changing the selection:

```bash theme={null}
mutagent providers list --workspace support-bots
```

Two workspaces with the same name: pass the id instead of the name.

## Which workspace a command uses

The first one set wins:

1. `--workspace <name|id>` on the command
2. the `MUTAGENT_WORKSPACE_ID` environment variable
3. the workspace chosen with `mutagent workspaces use` (or approved at login)

With none of them set, a command that needs a workspace stops with `WORKSPACE_REQUIRED` and exit code
3, and tells you what to run:

```text theme={null}
Error: No workspace selected. Run: mutagent workspaces use <name>
```

With `--json`, the same error is an object a script can act on. For `mutagent providers list --json`:

```json theme={null}
{
  "success": false,
  "error": "No workspace selected. Run: mutagent workspaces use <name>",
  "code": "WORKSPACE_REQUIRED",
  "suggestedAction": "mutagent workspaces use <name>",
  "_agentGuidance": {
    "helpCommand": "mutagent providers list --help",
    "suggestion": "mutagent workspaces use <name>",
    "fix": ["mutagent workspaces use <name>"],
    "notes": []
  }
}
```

When the key comes from `MUTAGENT_API_KEY`, there is no stored selection, so the hint names
`--workspace` and `MUTAGENT_WORKSPACE_ID` instead.

## Check the organization in scripts

`--org` on any command checks that the key belongs to that organization (by id, slug or name). On a
mismatch the command exits 1 and sends nothing, so a script never acts in the wrong organization:

```bash theme={null}
mutagent providers list --org acme --json
```

## What is shared across workspaces

LLM providers, Environments and managed agents belong to one workspace. Sandbox providers are
different: the Mutagent managed cloud is one sandbox provider shared by every workspace, so there is
nothing to configure per workspace. See
[Supported integrations](/get-started/supported-integrations#sandbox-providers).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.