Teams Management

The Teams feature (/dashboard/teams) lets administrators create organizational groups, add members, and assign team-level permissions. Teams can represent departments, project workgroups, or client groups.

Accessing the Teams pages requires the team.read permission. Creating or modifying teams requires team.write.

Data Model


interface Team {
  id:          string;
  name:        string;
  description: string | null;
  createdAt:   string;
  members: TeamMember[];
}
 
interface TeamMember {
  id:        number;
  userId:    string;
  teamId:    string;
  role:      'owner' | 'admin' | 'member';
  user: {
    id:    string;
    name:  string;
    email: string;
    image: string | null;
  };
}

API Endpoints

Method	Endpoint	Permission	Description
`GET`	`/api/teams`	`team.read`	List all teams (with members)
`GET`	`/api/teams/[id]`	`team.read`	Get a single team + members
`POST`	`/api/teams`	`team.write`	Create a new team
`PUT`	`/api/teams/[id]`	`team.write`	Update team name/description
`DELETE`	`/api/teams/[id]`	`team.write`	Delete a team
`POST`	`/api/teams/[id]/members`	`team.write`	Add a user to a team
`DELETE`	`/api/teams/[id]/members/[userId]`	`team.write`	Remove a user from a team
`PUT`	`/api/teams/[id]/members/[userId]`	`team.write`	Change a member’s team role
`GET`	`/api/teams/[id]/permissions`	`team.write`	Get team-level permissions
`PUT`	`/api/teams/[id]/permissions`	`team.write`	Update team-level permissions

Frontend API Client

Use teamsApi from src/services/teams/api.ts:


import { teamsApi } from '@/services/teams/api';
 
// List all teams
const { data: teams } = await teamsApi.getTeams();
 
// Get a specific team
const { data: team } = await teamsApi.getTeam(teamId);
 
// Create a team
const { data: newTeam } = await teamsApi.createTeam({
  name: 'Engineering',
  description: 'Core engineering team',
});
 
// Add a member
await teamsApi.addMember(teamId, { userId, role: 'member' });
 
// Remove a member
await teamsApi.removeMember(teamId, userId);
 
// Update member role
await teamsApi.updateMemberRole(teamId, userId, 'admin');
 
// Delete a team
await teamsApi.deleteTeam(teamId);

Dashboard UI

The Teams page provides:

Teams list — paginated table of all teams with member count
Create Team dialog — FormInput for name + description
Team detail view — lists all members with their roles
Add Member dialog — search users by name/email, select role
Member role editor — inline dropdown to change member → admin → owner
Remove member — confirmation dialog before removal

Using Teams in Your Code

Check if a user belongs to a team (server-side)


const membership = await prisma.teamMember.findFirst({
  where: {
    teamId: params.teamId,
    userId: session.user.id,
  },
});
 
if (!membership) {
  return NextResponse.json({ error: 'Not a team member' }, { status: 403 });
}

Check team membership role


if (membership.role !== 'owner' && membership.role !== 'admin') {
  return NextResponse.json({ error: 'Insufficient team role' }, { status: 403 });
}

Team-level permissions are additive — they stack on top of the user’s global role permissions. A user with user.read globally can be granted additional team-specific access without changing their global role.