Skip to main content

Collaboration

Teams

A team lets several VulnRadar accounts share scan reports and the resources attached to them. One account owns the team, everyone else joins by invitation, and a per-member team role decides what each person can do.

Distinct team roles
6
Teams owned (Pro / Elite)
1-3
Seats per team (Pro / Elite)
3-10

Overview

A team is a group of accounts that can see each other's scans once those scans are shared into the team. Exactly one account is the owner (set at creation, never handed out by invite), and every other member joins through an emailed or in-app invitation. Membership attaches to an account, not an email address alone, so accepting an invite requires being signed in as the account the invite was sent to.

The whole feature is gated behind the FEATURE_TEAMS flag. When it is off, the create endpoint returns 403 and no team routes do anything useful.

Creating a Team

POST /api/v3/teams with a name (2 to MAX_TEAM_NAME_LENGTH, 255 by default). The creator is inserted as the sole owner in the same transaction, and a URL slug is generated from the name plus a short timestamp suffix.

JSON
// POST /api/v3/teams
{ "name": "Platform Security" }

// 200
{
  "team": {
    "id": 42,
    "name": "Platform Security",
    "slug": "platform-security-lq9f3k",
    "role": "owner",
    "member_count": 1,
    "created_at": "2026-08-24T15:30:00.000Z"
  }
}
  • Rename: PATCH /api/v3/teams with { teamId, name }. Requires the manage_team permission (owner, admin, manager, operator).
  • Delete: DELETE /api/v3/teams with { teamId }. Owner-only (delete_team). The delete cascades to team_members and team_invites in one statement, so there is no half-deleted state.
  • First-run invites: the create dialog can pre-invite people as it makes the team. It caps the number of rows at the owner's seat limit minus one (their own seat), clamped to 10, and sends each invite as a separate call so the team is still created if one address fails.

Plan Limits

Two independent caps apply, and both are read from the owner's plan, not the plan of whoever is doing the inviting: how many teams an account may own, and how many seats a team may hold. A seat is one member plus one pending, unexpired invite, so outstanding invites count against the cap until they are accepted, declined, or expire.

Team ownership and seat limits per plan
PlanTeams ownedSeats per team
Free00
Core Supporter00
Pro Supporter13
Elite Supporter310
  • Teams are a Pro Supporter and above feature. Free and Core Supporter both resolve to 0 teams and 0 seats, so the create endpoint returns a plan-limit error for them.
  • 0 means the plan cannot use teams at all; -1 means unlimited. With billing disabled entirely (a self-hosted deployment), both caps are treated as unlimited.
  • The enforced numbers live in the admin Billing settings (resolved through lib/billing/plan-limits.ts), so an admin can retune them without a deploy. The values above are the shipped defaults, which also drive the pricing-page copy in lib/billing/catalog.ts.
  • Staff accounts are treated as the Pro Supporter plan here, not as unlimited.

Roles and Permissions

There are 6 team roles. They are built from four underlying capabilities: manage_team (rename the team), manage_members (invite, remove, change roles), manage_scans (create and edit team-scoped scans), and view_reports (read shared reports), plus the owner-only delete_team. Every role holds view_reports.

Team role capability matrix, from TEAM_ROLE_PERMISSIONS in lib/config/client-constants.ts
RoleRename teamManage membersRun/edit team scansView reportsDelete team
ownerYesYesYesYesYes
adminYesYesYesYesNo
managerYesYesNoYesNo
operatorYesNoYesYesNo
memberNoNoYesYesNo
viewerNoNoNoYesNo

Manager and operator are deliberate opposites: a manager handles people and settings but does not run scans, while an operator runs scans and adjusts settings but does not handle onboarding. That is why the roles are not a single ladder.

Role ceiling

Because the roles are a partial order rather than a strict ranking, a caller may only invite, promote, demote, or remove someone at a role whose permission set is a subset of the caller's own (the canAssignTeamRole check). Without it, a manager (who has manage_members but not manage_scans) could promote someone to admin and hand out a capability the manager itself lacks, or evict a higher-privileged admin. The owner holds every permission, so the owner can act on any role; the owner's own role can never be changed or removed through the member routes.

Invitations

POST /api/v3/teams/members with { teamId, email, role } sends an invite. role defaults to viewer and may be any role except owner. The caller needs manage_members, the role ceiling applies, and the request is rate-limited per user to stop invite spam from a compromised account.

  • The invite is rejected if the address is already a member, if an unexpired invite is already pending for it, or if adding a seat would exceed the owner's plan cap.
  • A 32-byte random token is generated. Only its SHA-256 hash is stored; the plaintext token appears only in the invite link, /teams/join?token=..., and in the one-time copy field shown in the UI right after sending (the only delivery path on a self-host with no SMTP).
  • Delivery is by email, and if the invited address already belongs to an account, an in-app bell notification is created too. Invites expire after TEAM_INVITE_EXPIRY_DAYS (7 by default).
  • Manage members: PATCH /api/v3/teams/members changes a role (you cannot change your own), DELETE /api/v3/teams/members removes a member (by userId) or cancels a pending invite (by inviteId). A non-owner removing their own userId leaves the team; the owner cannot leave and must transfer or delete instead.

Accepting an invite

Both accept paths go through POST /api/v3/teams/accept-invite and both require a signed-in session:

  • Emailed link: the /teams/join page reads the plaintext token from the URL and posts { token }. If the visitor is not logged in, it sends them to sign in and back.
  • In-app: the notification bell and the invitations panel on /teams post { inviteId } instead, since the plaintext token is never persisted.

Either way, the accept enforces that the signed-in account's email matches the invite's email (a 403 otherwise, so a guessed inviteId is useless), that the invite has not expired (400), and that you are not already a member (400). List your own pending invites with GET /api/v3/teams/invitations, and decline one with DELETE /api/v3/teams/invitations (scoped to your own email).

Sharing Scans

A scan is personal by default: its team_id is null and only its owner can see it, even between teammates. To share it, the owner assigns it to a team with PATCH /api/v3/history/{id} and a teamId in the body. Only the scan's own owner may change that assignment, and only to a team where they hold manage_scans.

Once a scan carries a team_id, access follows one shared rule (getTeamResourceAccess):

  • Any co-member with view_reports (all 6 roles) can read it.
  • Co-members with manage_scans (owner, admin, operator, member) can also edit its notes and visibility. Managers and viewers are read-only on shared scans.
  • Personal scans (team_id null) stay owner-only regardless of shared team membership.
  • Super-admin exception: if a shared resource's owner is a super-admin, team roles grant read but never write, so team sharing can never become a side channel for editing a super-admin's own data.

GET /api/v3/teams/member-scans?teamId=&userId= returns a member's scans assigned to that team only (most recent 50), never their personal scans. Both the requester and the target must be members of the team. GET /api/v3/teams/teammates returns everyone you share any team with, deduped across your teams, and is what populates the assignee picker when you hand a remediation item to a teammate.

Webhooks and Domains

Scans are not the only thing a team shares. Webhooks and verified domains can each carry a team_id too, and they use the same getTeamResourceAccess rule: a team-scoped webhook or domain is visible to every co-member and writable by those with manage_scans. The list endpoints for both (GET /api/v3/webhooks and GET /api/v3/domains) union your own rows with any row whose team you belong to, so shared and personal resources come back together.

API Endpoints

Every team route is session-authenticated. Bearer API keys are not accepted: you must be a logged-in user, the same rule the webhooks API uses.

Team API endpoints
MethodEndpointDescription
GET/api/v3/teamsList your teams, with your plan's team and seat caps.
POST/api/v3/teamsCreate a team. You become its owner.
PATCH/api/v3/teamsRename a team (needs manage_team).
DELETE/api/v3/teamsDelete a team (owner only).
GET/api/v3/teams/members?teamId=Members, pending invites, and your own role.
POST/api/v3/teams/membersInvite a member by email (needs manage_members).
PATCH/api/v3/teams/membersChange a member's role (needs manage_members).
DELETE/api/v3/teams/membersRemove a member, cancel an invite, or leave the team.
GET/api/v3/teams/invitationsYour own pending invitations.
DELETE/api/v3/teams/invitationsDecline one of your pending invitations.
POST/api/v3/teams/accept-inviteAccept an invite by token or by inviteId.
GET/api/v3/teams/teammatesEveryone you share a team with, deduped.
GET/api/v3/teams/member-scans?teamId=&userId=A member's scans assigned to that team.
Team Roles, Invitations, and Shared Scans | VulnRadar