---
title: User Groups
category: concept
slug: user-groups
summary: "Named collections of employees, optionally backed by Spaces."
---
# User Groups

Named collections of employees, optionally backed by Spaces.

A User Group is a named collection of @himarley.com users — think `@engineering`, `@slt`, `@design-partners`. The slug **is** the user-facing identifier.

Sharing a Droplet with 24 people no longer means pasting 24 emails. Add `@engineering` once and the grant tracks live membership: new joiners get access automatically; leavers lose it.

## Visibility

Every group has a single visibility setting that decides who sees the row in the directory and who can read the member roster:

- **PUBLIC** (default) — every signed-in @himarley user sees the group and its members.
- **MEMBERS_ONLY** — the group row is visible to everyone, but the member roster is hidden from non-members. The count still shows ("24 members"); the names don't.
- **ADMIN_ONLY** — the group is invisible to non-admins. Used by System Roles. People Admins always see admin-only groups.

## Sharing a Droplet with a group

In the Droplet's Share modal, type the group's display name or `@<slug>` into the "Add people or group" picker. The access list renders the group as a single row with a member-expansion toggle — not 24 individual chips. Grants are **live**: adjust group membership and the Droplet's audience updates without any re-saving on the Droplet side.

## Bootstrapping a Space from a group

When a group hardens into a long-lived team that wants its own collection of Droplets, the group detail page has a one-click **"Create Space from this group"** action. It creates a new [Space](/docs/spaces) with the group's slug + name, seeds the Space's membership from the group, and links the two so the relationship is discoverable from both sides.

## System Roles

System Roles are User Groups with one extra bit set: `systemRole: true`. They render in a pinned "System Roles" section at the top of the directory tab, visible only to People Admins. Two ship today:

- `@drop-people-admins` — curates the Directory, creates User Groups, edits visibility.
- `@drop-library-admins` — curates the [shared library](/docs/shared-library).

System role groups are protected: they can't be deleted via the standard endpoint, their slug can't be renamed, and their visibility is locked to ADMIN_ONLY. A last-admin guard prevents removing the only remaining member.


## Operations

### Create a User Group

Creation requires the People Admin role. Pick a slug that reads well as an `@`-mention.

**CLI**

```bash
drop groups create "Engineering" \
  --slug engineering \
  --description "The team building Drop and adjacent tools." \
  --visibility PUBLIC
```

**MCP**

```json
{
  "tool": "drop_create_group",
  "arguments": {
    "name": "Engineering",
    "slug": "engineering",
    "description": "The team building Drop and adjacent tools.",
    "visibility": "PUBLIC"
  }
}
```

**HTTP**

```bash
curl -X POST https://drop.himarley.ai/api/user-groups \
  -H "Authorization: Bearer $DROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "slug": "engineering",
    "description": "The team building Drop and adjacent tools.",
    "visibility": "PUBLIC"
  }'
```

### Add members

Bulk-add by email or user id. Adds are idempotent. A cascade preview shows the blast radius before the add commits — adding someone to a group silently expands their access to every Droplet currently shared with the group.

**CLI**

```bash
drop groups members add engineering \
  jane@himarley.com kai@himarley.com
```

**MCP**

```json
{
  "tool": "drop_group_add_members",
  "arguments": {
    "groupSlug": "engineering",
    "emails": ["jane@himarley.com", "kai@himarley.com"]
  }
}
```

**HTTP**

```bash
curl -X POST https://drop.himarley.ai/api/user-groups/engineering/members \
  -H "Authorization: Bearer $DROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["jane@himarley.com", "kai@himarley.com"]}'
```

### Bootstrap a Space from a group

Create a Space pre-seeded with the group's roster. Requires the People Admin role. The two stay linked so the relationship is discoverable from either side.

**CLI**

```bash
drop groups bootstrap-space engineering
```

**HTTP**

```bash
curl -X POST https://drop.himarley.ai/api/user-groups/engineering/bootstrap-space \
  -H "Authorization: Bearer $DROP_TOKEN"
```