diff --git a/api-reference/internal/delete-default-team-members.mdx b/api-reference/internal/delete-default-team-members.mdx new file mode 100644 index 00000000..7093c370 --- /dev/null +++ b/api-reference/internal/delete-default-team-members.mdx @@ -0,0 +1,69 @@ +--- +openapi: delete /v1/user/team/default-members +--- + +Remove default team members from your configuration. You can delete a specific member by email or clear all default members at once. + +## How It Works + +This endpoint provides two deletion modes: +- **Specific deletion**: Provide an `email` to remove a single default member +- **Clear all**: Send empty body `{}` to remove all default members + + + This only affects future team creation. Existing teams and their members remain unchanged. + + +## Request Body + +| Field | Type | Required | Description | +|---------|--------|----------|-------------| +| `email` | string | No | Email of specific member to remove. Omit to remove all | + +## Examples + +### Delete Specific Member + +```bash +curl -X DELETE "https://api.projectdiscovery.io/v1/user/team/default-members" \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Team-Id: YOUR_TEAM_ID" \ + -d '{ "email": "user@example.com" }' +``` + +**Response:** +```json +{ + "message": "default team member deleted successfully" +} +``` + +### Delete All Default Members + +```bash +curl -X DELETE "https://api.projectdiscovery.io/v1/user/team/default-members" \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Team-Id: YOUR_TEAM_ID" \ + -d '{}' +``` + +**Response:** +```json +{ + "message": "default team member deleted successfully" +} +``` + +## Alternative Approach + +Instead of deleting individual members, you can also use the [Set Default Team Members](/api-reference/internal/set-default-team-members) endpoint with an updated list, which replaces the entire configuration at once. + + + For bulk updates, using POST to replace the entire list is more efficient than multiple DELETE operations. + + +## Authorization + +Only **owner** or **admin** of the workspace (identified by `X-Team-Id`) can delete default members. diff --git a/api-reference/internal/get-default-team-members.mdx b/api-reference/internal/get-default-team-members.mdx new file mode 100644 index 00000000..49418350 --- /dev/null +++ b/api-reference/internal/get-default-team-members.mdx @@ -0,0 +1,31 @@ +--- +openapi: get /v1/user/team/default-members +--- + +Retrieve the list of members that will be automatically added to any new team/workspace created by the owner. This configuration eliminates the need to manually invite the same members every time a new team is created. + +## What You'll Get + +The response includes: +- List of configured default members with their emails and assigned roles +- Confirmation message + + + Only **owner** or **admin** of the workspace can retrieve default team members. + + +## Example Response + +```json +{ + "message": "successfully retrieved default team members", + "members": [ + { "email": "user1@example.com", "role": "MEMBER" }, + { "email": "user2@example.com", "role": "ADMIN" } + ] +} +``` + + + If no default members are configured, the `members` array will be empty. + diff --git a/api-reference/internal/set-default-team-members.mdx b/api-reference/internal/set-default-team-members.mdx new file mode 100644 index 00000000..795946f7 --- /dev/null +++ b/api-reference/internal/set-default-team-members.mdx @@ -0,0 +1,105 @@ +--- +openapi: post /v1/user/team/default-members +--- + +Configure a list of members that will be automatically added to any new team/workspace you create. This endpoint replaces any existing default member configuration. + +## How It Works + +When you set default members: +- **Replaces** any existing default member configuration +- **Validates** each member against your workspace plan limits +- **Deduplicates** members by email (keeps first occurrence) +- **Applies** to all future teams created by the owner + + + This operation **replaces** the entire default members list. To add or remove individual members, retrieve the current list, modify it, and send the updated version. + + +## Request Body + +Send an array of member objects, each containing: +- `email` (string, required): Member's email address +- `role` (string, required): One of `ADMIN`, `MEMBER`, `VIEWER`, or `GUEST` + + + The `OWNER` role cannot be assigned as a default member. Owner is always assigned automatically during team creation. + + +## Examples + +### Set Multiple Default Members + +```bash +curl -X POST "https://api.projectdiscovery.io/v1/user/team/default-members" \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Team-Id: YOUR_TEAM_ID" \ + -d '{ + "members": [ + { "email": "security-lead@example.com", "role": "ADMIN" }, + { "email": "team-member@example.com", "role": "MEMBER" }, + { "email": "auditor@example.com", "role": "VIEWER" } + ] + }' +``` + +**Response:** +```json +{ + "message": "default team members updated successfully (3 members)" +} +``` + +### Clear All Default Members + +```bash +curl -X POST "https://api.projectdiscovery.io/v1/user/team/default-members" \ + -H "Content-Type: application/json" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Team-Id: YOUR_TEAM_ID" \ + -d '{ "members": [] }' +``` + +**Response:** +```json +{ + "message": "default team members updated successfully (0 members)" +} +``` + +## Validation Rules + +### Email Validation +- Must be valid email format +- Invalid emails return `400` error: `"invalid email format: bad-email"` + +### Role Validation +- Must be one of: `ADMIN`, `MEMBER`, `VIEWER`, `GUEST` +- Invalid roles return `400` error: `"invalid role: INVALID. Valid roles are: ADMIN, MEMBER, VIEWER, GUEST"` + +### Plan Limits +- Default members count is validated against your workspace plan's `MaxTeamMembers` limit (minus 1 for owner) +- Exceeding limit returns `400` error: `"default members count (15) exceeds your plan limit of 10 members"` + +## Common Errors + +| Status | Scenario | Solution | +|--------|----------|----------| +| `400` | Invalid email format | Verify email addresses are properly formatted | +| `400` | Invalid role | Use only: `ADMIN`, `MEMBER`, `VIEWER`, `GUEST` | +| `400` | Exceeds plan limit | Reduce number of default members or upgrade plan | +| `403` | Not owner/admin | Only team owners and admins can configure defaults | + +## Behavior During Team Creation + +When a new team is created: +1. System checks if the owner has configured default members +2. Each default member's email **must exist** in the system +3. If any email doesn't correspond to an existing user, team creation returns `400` error +4. Default members are **directly added** to the new team (no invitation flow) +5. Owner is automatically skipped if present in default members list + + + Default members streamline team provisioning, especially when creating multiple teams or workspaces with consistent access patterns. + diff --git a/mint.json b/mint.json index a0d257f8..9546108d 100644 --- a/mint.json +++ b/mint.json @@ -535,6 +535,9 @@ "api-reference/internal/add-team-member", "api-reference/internal/delete-team-member", "api-reference/internal/update-team-member", + "api-reference/internal/get-default-team-members", + "api-reference/internal/set-default-team-members", + "api-reference/internal/delete-default-team-members", "api-reference/internal/get-team", "api-reference/internal/create-workspace", "api-reference/internal/delete-team", diff --git a/openapi.yaml b/openapi.yaml index b5914b7f..c3705b1a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3627,6 +3627,93 @@ paths: $ref: '#/components/requestBodies/InviteTeamMemberRequest' description: Accept team invite parameters: [] + /v1/user/team/default-members: + get: + summary: Get Default Team Members + operationId: get-v1-user-team-default-members + tags: + - internal + responses: + '200': + $ref: '#/components/responses/GetDefaultTeamMembersResponse' + '401': + $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' + '500': + $ref: '#/components/responses/ErrorResponse' + default: + $ref: '#/components/responses/ErrorResponse' + security: + - X-API-Key: [] + description: Retrieve the list of configured default team members + parameters: + - schema: + type: string + in: header + description: 'Retrieve the Team ID from: https://cloud.projectdiscovery.io/settings/team' + name: X-Team-Id + required: true + post: + summary: Set Default Team Members + operationId: post-v1-user-team-default-members + tags: + - internal + responses: + '200': + $ref: '#/components/responses/MessageResponse' + '400': + $ref: '#/components/responses/MessageResponse' + '401': + $ref: '#/components/responses/MessageResponse' + '403': + $ref: '#/components/responses/MessageResponse' + '500': + $ref: '#/components/responses/MessageResponse' + default: + $ref: '#/components/responses/ErrorResponse' + security: + - X-API-Key: [] + requestBody: + $ref: '#/components/requestBodies/SetDefaultTeamMembersRequest' + description: Set (replace) the list of default team members + parameters: + - schema: + type: string + in: header + description: 'Retrieve the Team ID from: https://cloud.projectdiscovery.io/settings/team' + name: X-Team-Id + required: true + delete: + summary: Delete Default Team Members + operationId: delete-v1-user-team-default-members + tags: + - internal + responses: + '200': + $ref: '#/components/responses/MessageResponse' + '400': + $ref: '#/components/responses/MessageResponse' + '401': + $ref: '#/components/responses/MessageResponse' + '403': + $ref: '#/components/responses/MessageResponse' + '500': + $ref: '#/components/responses/MessageResponse' + default: + $ref: '#/components/responses/ErrorResponse' + security: + - X-API-Key: [] + requestBody: + $ref: '#/components/requestBodies/DeleteDefaultTeamMemberRequest' + description: Delete default team members (specific or all) + parameters: + - schema: + type: string + in: header + description: 'Retrieve the Team ID from: https://cloud.projectdiscovery.io/settings/team' + name: X-Team-Id + required: true /v1/admin/team/member: post: summary: Add Team Member (Admin) @@ -18822,6 +18909,30 @@ components: - message - members - max_team_members + GetDefaultTeamMembersResponse: + description: Default team members response + content: + application/json: + schema: + type: object + properties: + message: + type: string + members: + type: array + items: + type: object + properties: + email: + type: string + role: + type: string + required: + - email + - role + required: + - message + - members StaticScanIPsResponse: description: '' content: @@ -20041,6 +20152,40 @@ components: type: string required: - email + SetDefaultTeamMembersRequest: + content: + application/json: + schema: + type: object + properties: + members: + type: array + items: + type: object + properties: + email: + type: string + role: + type: string + enum: + - ADMIN + - MEMBER + - VIEWER + - GUEST + required: + - email + - role + required: + - members + DeleteDefaultTeamMemberRequest: + content: + application/json: + schema: + type: object + properties: + email: + type: string + description: Email of specific member to remove. Omit to remove all AdminAddTeamMemberRequest: content: application/json: