Skip to content

Commit ba81173

Browse files
shivankar-singhshivankar-singh
committed
Add comprehensive documentation for internal team management API endpoints
Manually enhanced all 8 internal API endpoint pages with: Team Management Endpoints: - get-team.mdx: Added use cases, response info, and best practices - create-workspace.mdx: Added creation workflow, naming conventions, and warnings - update-team.mdx: Added update guidelines, limitations, and best practices - delete-team.mdx: Added critical warnings, prerequisites, and recommended workflow Team Member Management Endpoints: - get-team-members.mdx: Added member status info, auditing guidelines - add-team-member.mdx: Added role descriptions, invitation process, and scenarios - update-team-member.mdx: Added role transition examples and permission impacts - delete-team-member.mdx: Added security scenarios, workflows, and alternatives Each page now includes: ✅ Detailed descriptions and context ✅ Practical use cases ✅ Important notes and warnings ✅ Best practices and recommendations ✅ Step-by-step workflows ✅ Common scenarios and examples ✅ Security considerations
1 parent 2ee1d98 commit ba81173

File tree

8 files changed

+551
-8
lines changed

8 files changed

+551
-8
lines changed

‎api-reference/internal/add-team-member.mdx‎

Lines changed: 108 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,110 @@
11
---
22
openapi: post /v1/user/team/member
3-
---
3+
---
4+
5+
Invite a new member to join your team workspace. This endpoint sends an invitation email to the specified user, granting them access to your team's scans, assets, and configurations based on the assigned role.
6+
7+
## Use Cases
8+
9+
- **Team Expansion**: Add new security team members or collaborators
10+
- **Onboarding**: Automate new employee access provisioning
11+
- **Contractor Access**: Grant temporary access to external consultants
12+
- **Cross-Functional Collaboration**: Invite stakeholders from other departments
13+
- **Automated Provisioning**: Integrate with HR systems for access management
14+
15+
## Required Information
16+
17+
To invite a team member, provide:
18+
- **Email Address**: Valid email of the user to invite (must be unique)
19+
- **Role**: Member's role and permission level
20+
- **Custom Message** (optional): Personalized invitation message
21+
22+
## Available Roles
23+
24+
<Tabs>
25+
<Tab title="Owner">
26+
**Full Control**
27+
- Complete administrative access
28+
- Can delete the team
29+
- Manage billing and subscriptions
30+
- Add/remove any members
31+
- *Only one owner per team*
32+
</Tab>
33+
34+
<Tab title="Admin">
35+
**Administrative Access**
36+
- Manage team settings
37+
- Add/remove members (except owner)
38+
- Configure integrations
39+
- Manage scans and assets
40+
- Cannot delete team or change billing
41+
</Tab>
42+
43+
<Tab title="Member">
44+
**Standard Access**
45+
- Create and run scans
46+
- View and manage assets
47+
- Create templates
48+
- View team results
49+
- Cannot modify team settings
50+
</Tab>
51+
52+
<Tab title="Viewer">
53+
**Read-Only Access**
54+
- View scans and results
55+
- View assets and vulnerabilities
56+
- View templates
57+
- Cannot create or modify anything
58+
- Ideal for stakeholders and auditors
59+
</Tab>
60+
</Tabs>
61+
62+
## Invitation Process
63+
64+
<Steps>
65+
<Step title="API Call">
66+
Call this endpoint with the member's email and desired role
67+
</Step>
68+
69+
<Step title="Email Sent">
70+
ProjectDiscovery sends an invitation email to the provided address
71+
</Step>
72+
73+
<Step title="User Accepts">
74+
The invited user clicks the link in the email to accept the invitation
75+
</Step>
76+
77+
<Step title="Access Granted">
78+
Once accepted, the member gains immediate access to the team workspace
79+
</Step>
80+
</Steps>
81+
82+
<Note>
83+
Invitations expire after 7 days. If the user doesn't accept within this timeframe, you'll need to resend the invitation.
84+
</Note>
85+
86+
<Warning>
87+
Be cautious when assigning Admin or Owner roles. These roles have significant permissions that could impact your team's security posture and configurations.
88+
</Warning>
89+
90+
## Best Practices
91+
92+
1. **Principle of Least Privilege**: Assign the minimum role necessary for the user's responsibilities
93+
2. **Verification**: Double-check email addresses before sending invitations
94+
3. **Role Review**: Periodically audit member roles and adjust as responsibilities change
95+
4. **Onboarding Documentation**: Provide new members with documentation about your team's scanning policies
96+
5. **Monitor Pending**: Track invitation acceptance and follow up on pending invites
97+
98+
## Common Scenarios
99+
100+
**Scenario: Adding a Security Analyst**
101+
- Role: Member
102+
- Use Case: They need to run scans and analyze results but shouldn't modify team settings
103+
104+
**Scenario: Adding a Manager for Reporting**
105+
- Role: Viewer
106+
- Use Case: They need visibility into security posture but shouldn't make changes
107+
108+
**Scenario: Adding a Security Lead**
109+
- Role: Admin
110+
- Use Case: They need to manage team operations but shouldn't handle billing

‎api-reference/internal/create-workspace.mdx‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,36 @@
11
---
22
openapi: post /v1/user/team
3-
---
3+
---
4+
5+
Create a new team workspace in ProjectDiscovery Cloud Platform. This endpoint allows you to programmatically create team workspaces for collaborative security testing and vulnerability management.
6+
7+
## Use Cases
8+
9+
- **Organization Onboarding**: Automatically provision team workspaces during organization setup
10+
- **Multi-Tenant Applications**: Create isolated workspaces for different clients or departments
11+
- **Automated Provisioning**: Set up new teams through CI/CD or infrastructure-as-code workflows
12+
- **Team Management**: Programmatically manage multiple team environments
13+
14+
## Required Information
15+
16+
To create a workspace, you need to provide:
17+
- **Team Name**: A unique, descriptive name for the workspace
18+
- **Team Description** (optional): Additional context about the team's purpose
19+
- **Initial Settings**: Default configurations for the new workspace
20+
21+
## Important Notes
22+
23+
<Warning>
24+
Creating a team workspace is a significant operation. Ensure you have the necessary permissions and that the team name is unique within your organization.
25+
</Warning>
26+
27+
<Note>
28+
After successful creation, you'll receive a `team_id` that should be used for all subsequent team-related operations. Store this ID securely in your application.
29+
</Note>
30+
31+
## Best Practices
32+
33+
1. **Naming Convention**: Use clear, descriptive team names that reflect their purpose (e.g., "Security-Team-Production", "Client-ABC-Testing")
34+
2. **Documentation**: Maintain a record of created workspaces and their purposes
35+
3. **Access Control**: Immediately configure appropriate access controls after workspace creation
36+
4. **Cleanup**: Implement processes to remove unused workspaces to avoid clutter

‎api-reference/internal/delete-team-member.mdx‎

Lines changed: 120 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,122 @@
11
---
22
openapi: delete /v1/user/team/member
3-
---
3+
---
4+
5+
Remove a member from your team workspace, revoking their access to all team resources including scans, assets, vulnerabilities, and configurations. This endpoint immediately terminates the member's access to the team.
6+
7+
## Use Cases
8+
9+
- **Employee Offboarding**: Remove access when team members leave the organization
10+
- **Access Revocation**: Immediately remove unauthorized or compromised accounts
11+
- **Project Completion**: Remove temporary members after project-specific work concludes
12+
- **Security Incidents**: Quickly revoke access during security investigations
13+
- **Team Restructuring**: Remove members during organizational changes
14+
15+
## What Happens When You Delete a Member
16+
17+
**Immediate Effects:**
18+
- ✅ Member loses all access to team workspace
19+
- ✅ Cannot view scans, assets, or vulnerabilities
20+
- ✅ Cannot create or modify team resources
21+
- ✅ Removed from team member list
22+
- ✅ Cannot access team API keys or integrations
23+
24+
**What is Preserved:**
25+
- 📝 Audit logs showing member's historical actions
26+
- 📝 Scans and assets they created remain in the team
27+
- 📝 Their user account (outside the team) remains active
28+
29+
<Note>
30+
The member's email must be provided to identify who should be removed. You cannot remove the team owner through this endpoint.
31+
</Note>
32+
33+
## Important Considerations
34+
35+
<Warning>
36+
**Immediate Access Revocation:** This action takes effect immediately. The member will lose access to all team resources without warning. Consider communicating with the member before removal if appropriate.
37+
</Warning>
38+
39+
<Warning>
40+
**Cannot Remove Owner:** The team owner cannot be removed through this endpoint. To change team ownership, you must transfer ownership first, then the previous owner can be removed.
41+
</Warning>
42+
43+
## Recommended Workflow
44+
45+
<Steps>
46+
<Step title="Review Member Activity">
47+
Check the member's recent activity and ensure no critical operations are in progress
48+
</Step>
49+
50+
<Step title="Backup/Transfer Ownership">
51+
If the member owns critical resources, transfer or document them before removal
52+
</Step>
53+
54+
<Step title="Communicate (If Appropriate)">
55+
For planned removals, inform the member beforehand to allow proper handoff
56+
</Step>
57+
58+
<Step title="Remove Member">
59+
Call this endpoint with the member's email address
60+
</Step>
61+
62+
<Step title="Verify Removal">
63+
Confirm the member no longer appears in the team member list
64+
</Step>
65+
66+
<Step title="Audit & Document">
67+
Log the removal for compliance and future reference
68+
</Step>
69+
</Steps>
70+
71+
## Security Scenarios
72+
73+
**Scenario: Employee Resignation**
74+
- **Timing**: Remove on last day of employment
75+
- **Actions**:
76+
- Transfer ownership of critical scans/assets
77+
- Document their work for team continuity
78+
- Remove access at end of business day
79+
80+
**Scenario: Compromised Account**
81+
- **Timing**: Immediate removal
82+
- **Actions**:
83+
- Remove access immediately
84+
- Review their recent activity
85+
- Rotate any API keys they had access to
86+
- Investigate potential security impact
87+
88+
**Scenario: Contractor Project End**
89+
- **Timing**: After project delivery and sign-off
90+
- **Actions**:
91+
- Export any needed reports
92+
- Document findings they discovered
93+
- Remove access after final deliverables
94+
95+
## Best Practices
96+
97+
1. **Timely Removal**: Remove access promptly when no longer needed
98+
2. **Documentation**: Maintain records of who was removed and why
99+
3. **Transfer First**: Ensure critical work is transferred before removal
100+
4. **Audit Trail**: Review member's activity before removal for compliance
101+
5. **Communication**: When appropriate, inform the member of pending removal
102+
6. **Verify**: Confirm removal was successful and access is revoked
103+
104+
## Re-Adding Members
105+
106+
If you need to re-add a member after removal:
107+
- They must be invited again using the "Add Team Member" endpoint
108+
- They will need to accept a new invitation
109+
- Their previous role and permissions are not automatically restored
110+
- Consider their historical context when assigning new role
111+
112+
<Tip>
113+
Instead of removing and re-adding members, consider temporarily changing their role to "Viewer" if they might need access again in the future.
114+
</Tip>
115+
116+
## Alternative Options
117+
118+
Before removing a member, consider:
119+
- **Role Downgrade**: Change them to Viewer for read-only access
120+
- **Temporary Suspension**: Some systems support suspending instead of deleting
121+
- **Transfer Ownership**: If they own critical resources, transfer first
122+
- **Export Data**: Backup any member-specific configurations or work

‎api-reference/internal/delete-team.mdx‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,67 @@
11
---
22
openapi: delete /v1/user/team
3-
---
3+
---
4+
5+
Permanently delete a team workspace from ProjectDiscovery Cloud Platform. This is a destructive operation that removes all team data, including scans, assets, vulnerabilities, and configurations.
6+
7+
## ⚠️ Critical Information
8+
9+
<Warning>
10+
**This operation is irreversible!** Once a team is deleted, all associated data including scans, assets, vulnerabilities, templates, and configurations will be permanently removed and cannot be recovered.
11+
</Warning>
12+
13+
## Prerequisites
14+
15+
Before deleting a team, you must:
16+
17+
1. **Remove all team members**: The team must have **zero members** (only the owner remains)
18+
2. **Owner permissions**: Only the team owner can delete a team
19+
3. **Confirmation**: Understand that all team data will be lost permanently
20+
21+
## Use Cases
22+
23+
- **Workspace Cleanup**: Remove unused or test workspaces
24+
- **Organization Restructuring**: Delete deprecated teams during reorganization
25+
- **Compliance**: Remove teams as part of data retention policies
26+
- **Resource Management**: Clean up temporary or project-specific workspaces
27+
28+
## What Gets Deleted
29+
30+
When you delete a team, the following data is permanently removed:
31+
- All vulnerability scans and results
32+
- All discovered assets and enumeration data
33+
- All custom templates and configurations
34+
- All team settings and preferences
35+
- All scan histories and logs
36+
- All team-specific integrations
37+
38+
## Recommended Workflow
39+
40+
<Steps>
41+
<Step title="Export Important Data">
42+
Before deletion, export any scans, reports, or data you need to retain using the export endpoints.
43+
</Step>
44+
45+
<Step title="Remove Team Members">
46+
Delete or reassign all team members. The team must have 0 members before it can be deleted.
47+
</Step>
48+
49+
<Step title="Verify Prerequisites">
50+
Confirm you're the team owner and that all members have been removed.
51+
</Step>
52+
53+
<Step title="Delete Team">
54+
Call this endpoint with the team ID to permanently delete the workspace.
55+
</Step>
56+
</Steps>
57+
58+
<Note>
59+
If you need to preserve any team data, make sure to export it before deletion. There is no way to recover deleted team data.
60+
</Note>
61+
62+
## Alternative Options
63+
64+
Consider these alternatives before deleting:
65+
- **Archive Instead**: Keep the team but remove active members
66+
- **Transfer Ownership**: Assign the team to another user
67+
- **Export Data**: Back up important scans and configurations before deletion

‎api-reference/internal/get-team-members.mdx‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,43 @@
11
---
22
openapi: get /v1/user/team/member
3-
---
3+
---
4+
5+
Retrieve a complete list of all members in your team, including their roles, permissions, status, and invitation details. This endpoint provides comprehensive member information for team management and access control.
6+
7+
## Use Cases
8+
9+
- **Team Dashboard**: Display current team members and their roles in your UI
10+
- **Access Auditing**: Review who has access to your team workspace
11+
- **Permission Management**: Check member roles before granting access to resources
12+
- **Onboarding Status**: Track which invitations are pending acceptance
13+
- **Compliance**: Generate reports of team access for security audits
14+
15+
## Response Information
16+
17+
For each team member, you'll receive:
18+
- **User Details**: Email, name, and user ID
19+
- **Role & Permissions**: Member role (owner, admin, member, viewer)
20+
- **Status**: Active, pending invitation, or suspended
21+
- **Timestamps**: When they joined and last active
22+
- **Invitation Details**: For pending members, when invited and by whom
23+
24+
## Member Statuses
25+
26+
- **Active**: Member has accepted invitation and has full access
27+
- **Pending**: Invitation sent but not yet accepted
28+
- **Suspended**: Member access temporarily disabled
29+
30+
<Note>
31+
Only team members with appropriate permissions can view the full team member list. Viewers may have restricted access to certain member details.
32+
</Note>
33+
34+
<Tip>
35+
Use this endpoint to verify team composition before performing bulk operations or sending team-wide notifications.
36+
</Tip>
37+
38+
## Best Practices
39+
40+
1. **Cache Wisely**: Team member lists don't change frequently, consider caching with reasonable TTL
41+
2. **Filter Locally**: Retrieve all members once and filter/sort on the client side for better performance
42+
3. **Regular Audits**: Periodically review team membership to ensure access is appropriate
43+
4. **Status Monitoring**: Track pending invitations and follow up on unaccepted invites

0 commit comments

Comments
 (0)