Developer Docs

Outside Collaborators

The Outside Collaborators system allows an Organization to grant temporary or permanent access to specific Malets for external individuals (e.g. marketing agencies, contractors, temporary staff) without adding them to the full Organization workspace.

Architecture Overview

Collaborators are completely separate from Organization Members. A user can be a Collaborator without needing a Membership record for the organization. Their access is explicitly scoped to an array of maletIds with a set of permissions.

Concept Description
Sandboxing The user only sees and interacts with the specific Malets assigned to them via maletIds. They have no access to org-level features (billing, teams, settings).
Permissions Granular capabilities assigned directly on the collaborator record (VIEW_ONLY, EDIT_CONTENT, MANAGE_ORDERS, FULL_ACCESS).
Lifecycle Collaborators can be explicitly suspended or have an auto-expiring status (expiresAt).

Authorization Pattern

When checking access, the system evaluates:

  1. Is the user an Organization Admin? (If yes, allow full access).
  2. Is the user a member with a specific role over the Organization?
  3. Is the user an Outside Collaborator via organizationCollaborators scoped to the current maletId?

Entity Schema

Collaborator

Field Type Description
id ID! Unique identifier
userId ID! The outside user
organizationId ID! Organization this collaborator belongs to
maletIds [String!]! The specific Malets they can access (1+ required)
permissions [CollaboratorPermission!]! Explicit access rights
status CollaboratorStatus! Current state (ACTIVE, SUSPENDED, REVOKED)
expiresAt DateTime Auto-revoke TTL
note String Used by admins to track who/why
invitedBy ID! The admin who created the record
createdAt DateTime! Creation time

External Interfaces

Enums

CollaboratorStatus

Value Behavior
ACTIVE Normal sandboxed access
SUSPENDED Access temporarily paused (record maintained for easy restoration)
REVOKED Access permanently disabled (kept as history/audit log)

CollaboratorPermission

Value Behavior
VIEW_ONLY Can view the malet dashboard and analytics
EDIT_CONTENT Can manage products, blogs, and settings
MANAGE_ORDERS Can view and process orders and transactions
FULL_ACCESS Has complete control over the mapped Malets

GraphQL API

Queries

List Organization Collaborators

Returns all collaborators configures under an Organization. Requires MANAGE_MEMBERS org permission.

query OrganizationCollaborators($orgId: ID!) {
	organizationCollaborators(orgId: $orgId) {
		id
		userId
		maletIds
		permissions
		status
		expiresAt
	}
}

Mutations

Add Collaborator

mutation AddCollaborator($input: AddCollaboratorInput!) {
	addCollaborator(input: $input) {
		id
		userId
		maletIds
	}
}

Update Collaborator

Modify an existing collaborator to adjust scope, permissions, expiration, or status (e.g. suspend).

mutation UpdateCollaborator($input: UpdateCollaboratorInput!) {
	updateCollaborator(input: $input) {
		id
		maletIds
		permissions
		status
	}
}

Remove Collaborator

Permanently revokes a collaborator's access.

mutation RemoveCollaborator($input: RemoveCollaboratorInput!) {
	removeCollaborator(input: $input) {
		id
		status
	}
}

Security Model

Only users with the MANAGE_MEMBERS permission (typically OWNER or ADMIN) can grant, modify, or revoke Outside Collaborators.

Unlike Team Memberships (which allow Team LEADs to invite), the Collaborator boundary expands access to external parties, which constitutes a higher security risk. Therefore, it is strictly gated to top-level organization admins.