Skip to main content

Groups

Groups are shared identity graphs where multiple users collaborate on a common set of nodes, tags, and relationships. They enable team-based knowledge building while maintaining individual data sovereignty.

How Groups Work​

  1. A user creates a group — they become the group admin
  2. Admin invites members — members accept to join
  3. Members collaborate — create/edit group nodes and tags
  4. Permissions are granular — admins assign exposure profiles to control member access
  5. Members can share personal data — by linking a personal exposure profile to the group

Group Structure​

{
  "id": "group-uuid",
  "name": "Research Team",
  "description": "Shared identity graph for research",
  "deletion_policy": "transfer",
  "created_by": "user-uuid",
  "created_at": "2026-01-15T10:30:00Z",
  "is_active": true
}

Roles​

RoleCapabilities
AdminFull CRUD on group, members, invitations, nodes, tags, exposure profiles, connections
MemberRead group data, create/edit/delete nodes based on assigned exposure profile

Members without an assigned exposure profile are read-only by default.

Key Concepts​

Group Nodes vs Personal Nodes​

Group nodes belong to the group, not to any individual member. They are separate from personal identity graphs. When a member leaves, group nodes remain.

Data Sharing into Groups​

Members can share personal data with the group by linking a personal exposure profile. This controls exactly what personal nodes/tags the group can see — the member retains full control and can revoke at any time.

Group Exposure Profiles​

Admins create group-level exposure profiles that control what members can do:

{
  "name": "Read-Only Members",
  "tag_permissions": {
    "read": { "allow_all": true },
    "create": { "allow_all": false },
    "edit": { "allow_all": false },
    "delete": { "allow_all": false }
  }
}

These are assigned to members via PUT /groups/:id/members/:uid.

Group-to-Group Connections​

Groups can establish connections with other groups. An admin sends a connection request, and the target group's admin accepts or declines.

Deletion Policies​

When the last admin leaves a group:

  • disband (default) — Group is deactivated, all memberships and data shares are revoked
  • transfer — Admin role automatically transfers to the longest-tenured remaining member

Workflow​

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Create      │ →   │  Invite      │ →   │  Collaborate  │
│  Group       │     │  Members     │     │  on Nodes     │
└──────────────┘     └──────────────┘     └──────────────┘
                                                │
                           ┌────────────────────┤
                           ▼                    ▼
                    ┌──────────────┐     ┌──────────────┐
                    │  Share       │     │  Connect     │
                    │  Personal    │     │  with Other  │
                    │  Data        │     │  Groups      │
                    └──────────────┘     └──────────────┘