Skip to main content

Team Members Feature Documentation

Table of Contents

  1. Overview
  2. Architecture
  3. Database Schema
  4. Permissions System
  5. API Endpoints
  6. Invitation Flow
  7. Notification Integration
  8. Access Control
  9. Plan Limits
  10. Error Handling
  11. Examples

Overview

The Team Members feature enables project owners to invite team members to collaborate on specific projects with granular permissions. Team members can be granted access to:
  • Create new agents within the project
  • Manage knowledge (upload documents, add webpages)
  • Manage existing agents (with selective agent access)
  • Access all agents or only specific agents

Key Features

  • Email-based invitations: Invite team members by email address
  • Granular permissions: Fine-grained control over what team members can do
  • Selective agent access: Grant access to specific agents or all agents
  • Notification system: Automatic notifications when invitations are sent
  • Plan-based limits: Team member limits enforced based on subscription plan
  • Automatic project visibility: Team members automatically see projects they have access to

Architecture

The team members feature is built on three main components:
  1. Database Layer (app/database/queries/sql_team.py, app/database/repositories/repo_team.py)
    • Stores team invites and members
    • Manages invitation lifecycle
  2. Service Layer (app/services/project_access.py)
    • Centralizes access control logic
    • Handles permission checks
    • Manages team operations
  3. API Layer (app/routes/team.py, app/routes/notifications.py)
    • RESTful endpoints for team management
    • Notification handling for invitations

Component Relationships


Database Schema

Table: project_team_invites

Stores pending and completed team invitations. Indexes:
  • idx_team_invites_project on project_id
  • idx_team_invites_email on invitee_email
Constraints:
  • Foreign key to projects(id) with ON DELETE CASCADE
  • Unique constraint on (project_id, member_user_id) in members table

Table: project_team_members

Stores active team members with their permissions. Indexes:
  • idx_team_members_project on project_id
  • idx_team_members_user on member_user_id
Constraints:
  • Foreign key to projects(id) with ON DELETE CASCADE
  • Foreign key to project_team_invites(invite_id) with ON DELETE CASCADE
  • Unique constraint on (project_id, member_user_id)

Relationship to users Table

Team members are linked to the users table via member_user_id. The users table includes an email column that is used for:
  • Invitation lookups
  • Email-based user identification
  • Automatic invite claiming when users sign up

Permissions System

Permission Types

  1. can_create_agents
    • Allows creating new agents within the project
    • Required for: Creating agents via API
  2. can_manage_knowledge
    • Allows managing the knowledge base
    • Required for: Uploading documents, adding webpages, managing knowledge items
  3. can_manage_agents
    • Allows managing existing agents
    • Required for: Editing agent settings, updating agent configurations

Agent Access Control

Team members can have access to:
  • All agents: Set apply_to_all_agents = true
  • Specific agents: Set apply_to_all_agents = false and provide allowed_agent_ids array

Permission Hierarchy

Access Context

The ProjectAccessContext dataclass (in app/services/project_access.py) provides:

API Endpoints

Base URL

All team endpoints are prefixed with /api/team

Authentication

All endpoints require Clerk authentication via the @require_clerk_auth decorator, which injects user_id into the route handler.

1. List Team

GET /api/team/<project_id> Get all team members and pending invitations for a project. Authorization: Project owner only Response:
Notes:
  • Only returns invites with status = 'pending'
  • Members include email field from JOIN with users table
  • Both invites and members are sorted by created_at ASC
Error Responses:
  • 403 Forbidden: User is not the project owner
  • 404 Not Found: Project not found
  • 500 Internal Server Error: Server error

2. Create Invitation

POST /api/team/<project_id>/invites Create a new team invitation. Authorization: Project owner only Request Body:
Field Descriptions:
  • email (required): Email address of the user to invite (must be lowercase and exist in users table)
  • can_create_agents (boolean): Permission to create agents
  • can_manage_knowledge (boolean): Permission to manage knowledge
  • can_manage_agents (boolean): Permission to manage existing agents
  • apply_to_all_agents (boolean): If true, access to all agents; if false, only allowed_agent_ids
  • allowed_agent_ids (array): List of agent UUIDs (required if apply_to_all_agents is false)
Response:
Validation Rules:
  1. Email must exist in users table (user must have signed up)
  2. Cannot invite yourself
  3. User cannot already be a team member
  4. Cannot have duplicate pending invites for same email + project
  5. Must respect plan-based team member limits
Error Responses:
  • 400 Bad Request:
    • "Email is required"
    • "User with that email must sign up first" (email not found)
    • "pending_invite_exists" (duplicate pending invite)
    • "already_member" (user is already a team member)
    • "cannot_invite_self" (trying to invite yourself)
  • 403 Forbidden:
    • "Forbidden" (not project owner)
    • "Team member limit reached for your plan"
  • 404 Not Found: "Project not found"
  • 500 Internal Server Error: "Failed to create invite"
Side Effects:
  • Creates a notification of type team_access for the invitee
  • Notification includes invite details in payload

3. Cancel Invitation

DELETE /api/team/<project_id>/invites/<invite_id> Cancel a pending team invitation. Authorization: Project owner only Response:
Validation:
  • Only pending invites can be cancelled
  • Returns false if invite status is not pending
Error Responses:
  • 400 Bad Request: "Invite cannot be cancelled" (not pending)
  • 403 Forbidden: "Forbidden" (not project owner)
  • 404 Not Found:
    • "Project not found"
    • "Invite not found"
  • 500 Internal Server Error: "Failed to cancel invite"
Side Effects:
  • Sets invite status to "cancelled"
  • Deletes all related team_access notifications for this invite

4. Remove Team Member

DELETE /api/team/<project_id>/members/<member_id> Remove a team member from the project. Authorization: Project owner only Response:
Error Responses:
  • 403 Forbidden: "Forbidden" (not project owner)
  • 404 Not Found:
    • "Project not found"
    • "Member not found"
  • 500 Internal Server Error: "Failed to remove member"
Side Effects:
  • Member record is deleted from project_team_members
  • Member loses all access to the project and its agents

Invitation Flow

1. Invitation Creation

2. User Signup (Automatic Claiming)

When a new user signs up via Clerk:

3. Accepting Invitation

4. Declining Invitation

5. Cancelling Invitation


Notification Integration

Notification Type: team_access

When an invitation is created, a notification is automatically generated: Notification Structure:

Notification Endpoints

Respond to Team Notification:
  • POST /api/notifications/<notification_id>/respond
  • Body: { "action": "accept" | "decline" }
  • Updates both the invite status and notification state
Notification Cleanup:
  • When an invite is cancelled, all related team_access notifications are automatically deleted
  • Query: DELETE FROM notifications WHERE type = 'team_access' AND payload->>'invite_id' = $1

Access Control

ProjectAccessService

The ProjectAccessService centralizes all access control logic: Key Methods:
  1. require_permission(project_id, acting_user_id, permission, agent_id)
    • Resolves user’s role (owner or member)
    • Checks permissions
    • Returns ProjectAccessContext
    • Raises PermissionError if access denied
  2. _resolve_access(project_id, acting_user_id)
    • Determines if user is owner or member
    • Returns appropriate ProjectAccessContext
  3. create_invite(...)
    • Validates invitation
    • Creates invite and notification
  4. accept_invite(invite_id, user_id)
    • Validates and processes acceptance
  5. decline_invite(invite_id, user_id)
    • Validates and processes decline
  6. remove_member(project_id, acting_user_id, member_id)
    • Removes team member

Usage in API Routes

All project and agent routes use _require_project_access() helper:
Example Usage:

Agent Filtering

Team members with limited agent access have agents filtered:

Plan Limits

Team member limits are enforced based on subscription plans:

Limit Enforcement

The ProjectAccessService._team_member_limit() method:
Validation in create_invite():
Note: Limits are per user (project owner), not per project. A user with multiple projects shares the same team member limit across all projects.

Error Handling

Error Types

  1. PermissionError
    • Raised when user lacks required permissions
    • Returns 403 Forbidden
  2. ValueError
    • Raised for validation errors
    • Returns 400 Bad Request with specific error message
  3. Generic Exception
    • Logged via log_error()
    • Returns 500 Internal Server Error

Common Error Messages


Examples

Example 1: Create Invitation with Full Access

Request:
Response:

Example 2: Create Invitation with Limited Agent Access

Request:
This grants access to only 2 specific agents, with permission to manage knowledge and existing agents, but not to create new agents.

Example 3: Accept Invitation

Request:
Response:

Example 4: List Team

Request:
Response:

Example 5: Cancel Invitation

Request:
Response:

Implementation Details

Email Normalization

  • All emails are stored in lowercase
  • Email comparison is case-insensitive
  • Query: LOWER(invitee_email) = LOWER($2)

UUID Handling

  • All IDs (project_id, invite_id, member_id, agent_id) are UUIDs
  • When comparing UUIDs from database (which return as UUID objects) with string parameters, convert to string: str(invite["project_id"])

Automatic Project Visibility

When a team member accepts an invitation:
  1. Member record is created in project_team_members
  2. Project is automatically visible in the member’s project list
  3. The list_projects endpoint includes both owned projects and projects where user is a member
  4. Response includes access_role: "owner" | "member" field

Data Consistency

  • When a project is deleted, all related invites and members are cascade deleted
  • When an invite is deleted, related notifications are deleted
  • When a member is removed, they immediately lose access (no soft delete)

Testing Considerations

Test Scenarios

  1. Invitation Creation
    • Valid invitation
    • Duplicate pending invite
    • Email not in users table
    • Inviting self
    • Already a member
    • Exceeding plan limits
  2. Invitation Acceptance
    • Valid acceptance
    • Accepting someone else’s invite
    • Accepting already accepted invite
    • Accepting cancelled invite
  3. Access Control
    • Owner has full access
    • Member with full agent access
    • Member with limited agent access
    • Member without permissions
  4. Notifications
    • Notification created on invite
    • Notification deleted on cancel
    • Notification updated on accept/decline

Future Enhancements

Potential improvements for the team members feature:
  1. Email Notifications
    • Send actual email when invitation is created
    • Include invitation link with token
  2. Role-Based Permissions
    • Predefined roles (Admin, Editor, Viewer)
    • Custom role creation
  3. Bulk Operations
    • Invite multiple users at once
    • Bulk remove members
  4. Activity Logging
    • Track who invited whom
    • Track permission changes
  5. Transfer Ownership
    • Transfer project ownership to team member
  6. Invitation Expiration
    • Currently set to 14 days, but not enforced
    • Could add automatic cleanup of expired invites


Support

For questions or issues related to the team members feature, please refer to:
  • Backend code: app/routes/team.py, app/services/project_access.py
  • Database queries: app/database/queries/sql_team.py
  • Repository: app/database/repositories/repo_team.py