Sharing & Resource Assignment

Assignment determines who can access and see a given instance of data. Instances (a specific conversation, listing, or document) are explicitly assigned to users or groups, and visibility is based on these assignments. See Visibility & Privacy for how the two work together.

What is Assignment?

Assignment is the mechanism that links a specific instance to users or groups. An instance's visibility depends on whether the current user (or one of their groups) is in its assigned_to list. Admins bypass this check entirely.

Assignment Targets

Target	Description	Example
Individual users	Specific people, named directly	A conversation assigned to exactly the two people in it
Groups	Every member of a group, resolved dynamically	A document assigned to the admin and moderators groups
Mixed	A combination of individuals and groups on the same instance	A shipment assigned to its creator plus the whole cargo_owner group

Assignment Patterns

Pattern	Description	Example
One-to-one	Two specific users, nobody else	A direct conversation between User A and User B. Adding User C requires an explicit assignment
One-to-many (broadcast)	One creator, one group of recipients	An admin announcement assigned to group_all_users, seen by everyone in the platform
Many-to-many	Several individuals plus a group, all collaborating	A team workspace assigned to three named users and group_project_team

Assignment Lifecycle

Creation: assignment is usually set automatically. Creating a conversation, for example, only requires the other party's ID and a message; assigned_to is set behind the scenes to [@self, @other_user] with no separate assignment step.

Modification: assignments are added or removed by identifying the instance, its type, and the user in question. Adding a moderator to an existing conversation simply appends the moderator's ID to that conversation's assigned_to list, the original participants stay assigned, and the moderator gains access alongside them. Removing a user works the same way in reverse.

Deletion: when an instance is deleted, its assignment list is cleared along with it.

Assignment Scenarios

Scenario	Assigned To	Who Can See It	Notes
One-to-one chat	[user_a, user_b]	Only User A and User B	A third user querying the conversation gets a 404: they're not in assigned_to, so its existence isn't leaked
Adding a third party (e.g. a moderator)	[user_a, user_b, moderator]	User A, User B, and the moderator	The moderator can see the full conversation history, subject to their own visibility rules
Group-wide announcement	[group_all_users]	Every member of the group	Works for any group size: a user added to the group later sees it immediately; removed, they lose access immediately
Selective team/project sharing	[user_a, user_b, user_c, group_project_leads]	Only the named users and the group's members	Others querying the project get a 404, not a 403

Assignment Permissions

Who Can Assign?

Permission to assign or unassign depends on the type:

Type	Who Can Assign	Who Can Unassign
Conversation	Owner (creator), admins, moderators	Owner, admins
Document	Owner	Owner, admin
Listing	Locked at creation (creator only)	Admin (reassignment only)

Assignment & Visibility

Assignment and visibility work together: a user sees an instance if they're directly in its assigned_to list, if one of their groups is, or if they're an admin. For example, a user in [cargo_owner, premium_subscriber] querying a conversation assigned to [user_xyz, group_moderators] will not see it. Neither their user ID nor either of their groups appears in the assignment list, and they aren't an admin.

Assignment is, in fact, the only mechanism by which a group affects visibility. A group doesn't carry its own separate visibility rule. If group_moderators can see flagged conversations, it's because that group is in those conversations' assigned_to list, not because of a rule attached to the group itself.

Assignment at Scale

Approach	Example	Why
Assign to a group	assigned_to: [group_cargo_owners]	One entry covers every member; the platform resolves membership dynamically
Assign to thousands of individuals	assigned_to: [user_1, user_2, ..., user_5000]	Avoid this: it doesn't track membership changes and doesn't scale

Group assignment also stays current automatically: a new member sees the instance the moment they join the group, and a departing member loses access the moment they leave, no manual reassignment needed.

Assignment & Copying

When an instance is copied for a new version (e.g. proposing changes to a matched listing), the copy starts with a narrower assignment than the original, then widens again once published:

flowchart LR
    A["Original listing (matched)<br/>assigned_to: [user_a, user_b]"] -->|copy for edits| B["Draft copy<br/>assigned_to: [user_a]"]
    B -->|published| C["Published copy<br/>assigned_to: [user_a, user_b]"]

API Operations

The assignment operations described above are backed by a small set of API operations: listing who an instance is assigned to, checking whether a specific user can access it, assigning many users at once, and clearing an instance's assignment list entirely. See GraphQL Implementation for the exact queries and mutations.

Assignment Audit

Timestamp	Actor	Action	Instance	Detail
2025-01-15 10:30	admin@company.com	User assigned	Conversation conv_123	Added john@company.com; assignees went from [user_a, user_b] to [user_a, user_b, john]
2025-01-16 14:22	system	Group assigned	Announcement ann_456	Assigned cargo_owners group (1000+ members resolved dynamically)

Best Practices

1. Use groups for scale: prefer assigned_to: [group_admins] over listing every individual admin
2. Owner + group pattern: combine a creator with a group, e.g. assigned_to: [user_a, group_project_team], so the creator always has access and the team has access through the group
3. Document who can assign/unassign: make the assign and unassign permissions for each type explicit (see the Who Can Assign? table above)
4. Keep initial assignment stable: once an instance is created, avoid changing its initial assignment unless there's a clear exception
5. Require explicit sharing: a "Share with User X" action is preferred over auto-sharing with all connected users