Team Members Feature Documentation
Table of Contents
- Overview
- Architecture
- Database Schema
- Permissions System
- API Endpoints
- Invitation Flow
- Notification Integration
- Access Control
- Plan Limits
- Error Handling
- 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:-
Database Layer (
app/database/queries/sql_team.py,app/database/repositories/repo_team.py)- Stores team invites and members
- Manages invitation lifecycle
-
Service Layer (
app/services/project_access.py)- Centralizes access control logic
- Handles permission checks
- Manages team operations
-
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_projectonproject_ididx_team_invites_emailoninvitee_email
- Foreign key to
projects(id)withON 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_projectonproject_ididx_team_members_useronmember_user_id
- Foreign key to
projects(id)withON DELETE CASCADE - Foreign key to
project_team_invites(invite_id)withON 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
-
can_create_agents- Allows creating new agents within the project
- Required for: Creating agents via API
-
can_manage_knowledge- Allows managing the knowledge base
- Required for: Uploading documents, adding webpages, managing knowledge items
-
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 = falseand provideallowed_agent_idsarray
Permission Hierarchy
Access Context
TheProjectAccessContext 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:
- Only returns invites with
status = 'pending' - Members include
emailfield from JOIN withuserstable - Both invites and members are sorted by
created_atASC
403 Forbidden: User is not the project owner404 Not Found: Project not found500 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:
email(required): Email address of the user to invite (must be lowercase and exist inuserstable)can_create_agents(boolean): Permission to create agentscan_manage_knowledge(boolean): Permission to manage knowledgecan_manage_agents(boolean): Permission to manage existing agentsapply_to_all_agents(boolean): Iftrue, access to all agents; iffalse, onlyallowed_agent_idsallowed_agent_ids(array): List of agent UUIDs (required ifapply_to_all_agentsisfalse)
- Email must exist in
userstable (user must have signed up) - Cannot invite yourself
- User cannot already be a team member
- Cannot have duplicate pending invites for same email + project
- Must respect plan-based team member limits
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"
- Creates a notification of type
team_accessfor 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:
- Only pending invites can be cancelled
- Returns
falseif invite status is notpending
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"
- Sets invite status to
"cancelled" - Deletes all related
team_accessnotifications 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:
403 Forbidden:"Forbidden"(not project owner)404 Not Found:"Project not found""Member not found"
500 Internal Server Error:"Failed to remove member"
- 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
- When an invite is cancelled, all related
team_accessnotifications are automatically deleted - Query:
DELETE FROM notifications WHERE type = 'team_access' AND payload->>'invite_id' = $1
Access Control
ProjectAccessService
TheProjectAccessService centralizes all access control logic:
Key Methods:
-
require_permission(project_id, acting_user_id, permission, agent_id)- Resolves user’s role (owner or member)
- Checks permissions
- Returns
ProjectAccessContext - Raises
PermissionErrorif access denied
-
_resolve_access(project_id, acting_user_id)- Determines if user is owner or member
- Returns appropriate
ProjectAccessContext
-
create_invite(...)- Validates invitation
- Creates invite and notification
-
accept_invite(invite_id, user_id)- Validates and processes acceptance
-
decline_invite(invite_id, user_id)- Validates and processes decline
-
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:
Agent Filtering
Team members with limited agent access have agents filtered:Plan Limits
Team member limits are enforced based on subscription plans:Limit Enforcement
TheProjectAccessService._team_member_limit() method:
create_invite():
Error Handling
Error Types
-
PermissionError- Raised when user lacks required permissions
- Returns
403 Forbidden
-
ValueError- Raised for validation errors
- Returns
400 Bad Requestwith specific error message
-
Generic
Exception- Logged via
log_error() - Returns
500 Internal Server Error
- Logged via
Common Error Messages
Examples
Example 1: Create Invitation with Full Access
Request:Example 2: Create Invitation with Limited Agent Access
Request:Example 3: Accept Invitation
Request:Example 4: List Team
Request:Example 5: Cancel Invitation
Request: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:- Member record is created in
project_team_members - Project is automatically visible in the member’s project list
- The
list_projectsendpoint includes both owned projects and projects where user is a member - 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
-
Invitation Creation
- Valid invitation
- Duplicate pending invite
- Email not in users table
- Inviting self
- Already a member
- Exceeding plan limits
-
Invitation Acceptance
- Valid acceptance
- Accepting someone else’s invite
- Accepting already accepted invite
- Accepting cancelled invite
-
Access Control
- Owner has full access
- Member with full agent access
- Member with limited agent access
- Member without permissions
-
Notifications
- Notification created on invite
- Notification deleted on cancel
- Notification updated on accept/decline
Future Enhancements
Potential improvements for the team members feature:-
Email Notifications
- Send actual email when invitation is created
- Include invitation link with token
-
Role-Based Permissions
- Predefined roles (Admin, Editor, Viewer)
- Custom role creation
-
Bulk Operations
- Invite multiple users at once
- Bulk remove members
-
Activity Logging
- Track who invited whom
- Track permission changes
-
Transfer Ownership
- Transfer project ownership to team member
-
Invitation Expiration
- Currently set to 14 days, but not enforced
- Could add automatic cleanup of expired invites
Related Documentation
- Notifications System - Details on the notification system
- Project Access Control - How access control is enforced
- API Authentication - Clerk authentication setup
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
