# Spaces, roles and permissions

> How Team Cloud organizes team data into spaces, the difference between open and restricted spaces, team and space roles, console roles, and who enforces each permission.

Source: https://docs.subcloak.com/cloak-proxy/team/spaces-and-roles/

Added in Cloak Proxy 0.7.0.

{/* L9 draft. Sources: PLAN 3.1–3.4, 7.1–7.3, 7.14 (who can create spaces), 9.5, 10; T6, T6.1, T6.2. Re-check labels against L8. */}

Everything a team shares lives in **spaces**. A space is one workspace, rule set, mock set, vault folder or other shared thing, with its own list of who can do what. This page covers the kinds of space, the roles people have in the team and in each space, and who enforces each permission.

## Kinds of space

{/* T6 */}

| Space | Holds | Who can read it by default |
|---|---|---|
| **Workspace** | An API client workspace: collections, folders, requests, environments, specs, flows, datasets and packages | Everyone in the team |
| **Rules** | A rule set | Everyone |
| **Mocks** | A mock set | Everyone |
| **Library** | Saved sessions with tags. See [Library and Findings](https://docs.subcloak.com/cloak-proxy/team/library-and-findings/) | Everyone |
| **Findings** | Team findings and bug reports | Everyone |
| **Agents** | Shared MCP servers and agent setups. See [Shared agent setups](https://docs.subcloak.com/cloak-proxy/team/agent-setups/) | Everyone |
| **Vault folder** | Secrets. See [Team vault](https://docs.subcloak.com/cloak-proxy/team/vault/) | Only the people added to it (always restricted) |

The first admin's Mac creates **Team rules**, **Team mocks**, **Library**, **Findings** and **Agents**. Anyone can create more spaces, unless the policy **Who can create spaces** is set to admins. {/* PLAN 6.2 step 5, 7.14 */}

## Open and restricted spaces

{/* PLAN 0, 3.2; T6 */}

- **Open** spaces are readable by every member of the team. They're encrypted with the team key, which every member's Mac holds.
- **Restricted** spaces ("only people I choose") are readable only by the people listed in them. Each has its own key, which a Mac receives only through a signed grant. Every vault folder is restricted.

Whether a space is restricted is chosen when it's created and never changes. To restrict an existing open space, choose **Move to a Restricted Space…** on it: Cloak Proxy creates a new restricted space and copies the items into it. {/* T6 v1, T20 item 22 (overrides PLAN 3.2, 7.3) */}

A restricted space's key is also sealed to the [Team Recovery Kit](https://docs.subcloak.com/cloak-proxy/team/team-keys/). Admins can't read a restricted space unless they're listed in it, and only its managers can change its access list, admins included: to cut someone off from it, remove them from the team, or ask one of its managers. {/* T6.1 v1, T20 item 23 (overrides PLAN 3.1), PLAN 12.2 malicious admin */}

## Team roles

{/* PLAN 3.1 */}

| Role | Can |
|---|---|
| **Admin** | Approve a new member's first Mac (each member approves their own further Macs); add, remove and change members' roles; create CI tokens; turn on [automatic approval after SSO](https://docs.subcloak.com/cloak-proxy/team/invite-and-approve/#approve-macs-automatically-after-sso); act as **Manager** in every open space. In a restricted space, an admin has only the role it lists them with: only its managers change who's listed |
| **Member** | Use the team's open spaces at the role each space gives them; use restricted spaces they're listed in; add their own further Macs; leave |
| **CI** | A [CI token](https://docs.subcloak.com/cloak-proxy/team/ci/): read the spaces granted to it, and upload recordings to open library spaces that allow it. Uploading gives no read access |

## Space roles

{/* PLAN 3.2; T6.1 */}

| Role | Can |
|---|---|
| **Viewer** | Read and comment |
| **Editor** | Viewer, plus change the space. In a rule or mock set, a manager approves each change before it applies; in a [protected](https://docs.subcloak.com/cloak-proxy/team/protected-sets/) set, propose changes |
| **Manager** | Editor, plus approve proposals, change who has which role, and make the set protected |

An open space gives every member a default role, **Editor** unless a manager sets it to **Viewer**, and can list people with other roles. In an open space everyone can at least read: to keep a space from some members, use a restricted space (**Move to a Restricted Space…** copies an open one into a new restricted space). A restricted space lists every person and their role. {/* T6.1: "none" not allowed for an open space */}

To see or change roles, open the space's **Info** sheet, or **Settings › Team** for team roles. The console shows team roles, and per-space counts by id: space names are encrypted, so only the app shows them. {/* PLAN 7.3 */}

## Who enforces what

{/* PLAN 3.4 */}

Every control is enforced by the keys themselves (cryptographic), by Subcloak's server, by Cloak Proxy on each Mac, or by more than one of them.

| Control | Cryptographic | Subcloak's server | Cloak Proxy on each Mac |
|---|---|---|---|
| Who can read a space | **Yes** (keys) | Also refuses downloads to non-members | — |
| Who can write a space, approve, or change who has access | **Yes** (every Mac checks the signatures) | **Yes** (refuses the write) | — |
| Who is a member, their role, which Macs are theirs | **Yes** (signed member list) | **Yes** | — |
| Removing a member stops access | At the next key change, by an admin's Mac | **Immediately** | Macs delete local team data (best effort) |
| Seats, billing, invitations, SSO-required sign-in, SCIM | — | **Yes** | — |
| [Policies](https://docs.subcloak.com/cloak-proxy/team/policies/) | Per policy | Per policy | Per policy |
| Monitors, hosted mocks\* | — (not end-to-end) | **Yes** | A warning before publishing |

Because writes are checked twice, a server that let a forbidden write through still couldn't make it apply: every Mac skips a change the space's access list doesn't allow.

## Console roles

{/* PLAN 3.3, 9.4 */}

The console has its own roles, kept by Subcloak's server. They decide what people can do on `console.subcloak.com`, never what they can read: the console holds no keys (unless an admin turns on automatic approval after SSO, which lets the server and your identity provider admit a Mac).

| Role | Seat | Can |
|---|---|---|
| **Owner** (exactly one) | Optional | Everything in the console: billing, seats, members, policies, SSO and SCIM, revoking CI tokens, monitors and hosted mocks, audit export, console users, delete the team (ownership transfers go through team support) |
| **Billing manager** | No | Billing, invoices and the seat count |
| **Admin** | Yes | Members, invitations, policies, SSO and SCIM, CI tokens, monitors, hosted mocks, usage and the audit log; not billing |
| **Member** | Yes | Their own profile, notification preferences, sessions and passkeys |

The owner adds billing managers in **Settings** in the console. Transferring ownership isn't in the console yet: the owner writes to [team-support@subcloak.com](mailto:team-support@subcloak.com) from the owner's address, and we make the change only after checking it's the owner and that the new owner agrees.

## Rule sets and mock sets

{/* PLAN 7.2 */}

Team rule and mock sets don't change your traffic until you choose them. In **Rules › Team Sets**, switch on each set you want on this Mac.

To fill a set, an editor or manager chooses **Add From This Mac…** in its menu in **Rules › Team Sets** and ticks some of their own rules (or mock sets): copies go into the team set, and their own stay as they are. The copies are readable by everyone in the set and stay in its 90-day history, including any tokens in scripts, rewrites and mock bodies (sensitive headers are removed from mock copies). In a protected set the copies wait on that Mac until they're sent with **Propose Change…**.

- **Rules › Team Sets** lists the sets of the team you're viewing, and only those sets apply on your Mac. They apply after your own rules; where one of your rules and a team rule cover the same thing (the same item, or a DNS spoof for the same host), yours wins.
- Sets you leave off are listed but do nothing. A set that's deleted, or that you can no longer read, stops applying, and so does every set on a Mac the team cut off.
- A rule or mock set in a team set applies only once a manager of that set has approved its current content: blocks, allows, rewrites, scripts, Map Local, Map Remote, DNS spoofs, alerts and mock sets alike. Until then it stays switched off on every Mac and in CI (`cloakctl team pull` exports it switched off too).
- In an open set, a manager approves in **Held Items…**, in the set's menu in **Rules › Team Sets**, after checking each item's content there. The approval names exactly that content and counts only in its own set: any later change, by anyone, is held again until approved. What a manager adds with **Add From This Mac…** comes approved. In a [protected set](https://docs.subcloak.com/cloak-proxy/team/protected-sets/), changes apply through approved proposals; an item added while the set was open stays held until it's sent with **Propose Change…**.
- Breakpoints, network conditions and failure scenarios in a team set never run on Macs (they'd change every member's traffic at once); once approved, they apply in CI runs. A team mock set answers only while your **Mock Sets** switch is on, and **Host on Subcloak's Servers*** publishes only its approved mock sets.
- In a team workspace, a request a teammate changed is sent without vault values and isn't monitored until you approve the change: in **Settings › Team**, click **Review…** next to Sync, as in [Personal Cloud](https://docs.subcloak.com/cloak-proxy/cloud/review-changes/).

## Workspaces

{/* PLAN 7.1 */}

A team workspace is an API client workspace everyone shares. Changes show on every member's Mac within seconds while they're online.

- If two people change the same record at once, the last change wins and the other is kept as a conflict copy, as in Personal Cloud.
- Secret environment values never sync. In a team, use `{{vault:team/NAME}}` references to the [team vault](https://docs.subcloak.com/cloak-proxy/team/vault/), which Cloak Proxy fills in on your Mac when a request is sent.
- Git still works for anyone who prefers it. **Copy to Team…** turns a local or Git workspace into a team copy.

## Related

  - [Protected sets and reviews](https://docs.subcloak.com/cloak-proxy/team/protected-sets/): Proposals, approvals and bypass.
  - [Team vault](https://docs.subcloak.com/cloak-proxy/team/vault/): Restricted folders for secrets.
  - [Policies](https://docs.subcloak.com/cloak-proxy/team/policies/): Team-wide settings and who enforces them.
  - [Security model](https://docs.subcloak.com/cloak-proxy/team/security-model/): How the checks work.