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.
// 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/teamswith{ teamId, name }. Requires themanage_teampermission (owner, admin, manager, operator). - Delete:
DELETE /api/v3/teamswith{ teamId }. Owner-only (delete_team). The delete cascades toteam_membersandteam_invitesin 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.
| Plan | Teams owned | Seats per team |
|---|---|---|
| Free | 0 | 0 |
| Core Supporter | 0 | 0 |
| Pro Supporter | 1 | 3 |
| Elite Supporter | 3 | 10 |
- 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.
0means the plan cannot use teams at all;-1means 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 inlib/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.
| Role | Rename team | Manage members | Run/edit team scans | View reports | Delete team |
|---|---|---|---|---|---|
| owner | Yes | Yes | Yes | Yes | Yes |
| admin | Yes | Yes | Yes | Yes | No |
| manager | Yes | Yes | No | Yes | No |
| operator | Yes | No | Yes | Yes | No |
| member | No | No | Yes | Yes | No |
| viewer | No | No | No | Yes | No |
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/memberschanges a role (you cannot change your own),DELETE /api/v3/teams/membersremoves a member (byuserId) or cancels a pending invite (byinviteId). A non-owner removing their ownuserIdleaves 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/joinpage reads the plaintexttokenfrom 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
/teamspost{ 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).
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.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v3/teams | List your teams, with your plan's team and seat caps. |
| POST | /api/v3/teams | Create a team. You become its owner. |
| PATCH | /api/v3/teams | Rename a team (needs manage_team). |
| DELETE | /api/v3/teams | Delete a team (owner only). |
| GET | /api/v3/teams/members?teamId= | Members, pending invites, and your own role. |
| POST | /api/v3/teams/members | Invite a member by email (needs manage_members). |
| PATCH | /api/v3/teams/members | Change a member's role (needs manage_members). |
| DELETE | /api/v3/teams/members | Remove a member, cancel an invite, or leave the team. |
| GET | /api/v3/teams/invitations | Your own pending invitations. |
| DELETE | /api/v3/teams/invitations | Decline one of your pending invitations. |
| POST | /api/v3/teams/accept-invite | Accept an invite by token or by inviteId. |
| GET | /api/v3/teams/teammates | Everyone you share a team with, deduped. |
| GET | /api/v3/teams/member-scans?teamId=&userId= | A member's scans assigned to that team. |