Feature: Add Team/User Management REST Endpoints and Dataset/Canvas Permission Framework

[hetavi-bluexkye]

New REST API Endpoints

Below is the list of all the new REST API endpoints added in the feature branch feature/OND211-2329-Check-existing-REST-endponts-and-extend-with-new-requested-endpoints.

---

Team Management Endpoints

All team management endpoints are under the /tenant base path and require authentication.

1. Create Team

Endpoint: POST /tenant/create

Description: Create a new team (tenant). Requires authentication - any registered user can create a team.

Request Body:

{
  "name": "string (required, max 100 characters)",
  "user_id": "string (optional, defaults to current authenticated user)",
  "llm_id": "string (optional, defaults to system default)",
  "embd_id": "string (optional, defaults to system default)",
  "asr_id": "string (optional, defaults to system default)",
  "parser_ids": "string (optional, defaults to system default)",
  "img2txt_id": "string (optional, defaults to system default)",
  "rerank_id": "string (optional, defaults to system default)",
  "credit": "integer (optional, defaults to 512)"
}

Response: Returns created team information with ID, name, owner_id, and model IDs.

Status Codes:

• 200 - Team created successfully
• 400 - Invalid request or user not found
• 401 - Unauthorized - authentication required
• 500 - Server error during team creation

---

2. Update Team

Endpoint: PUT /tenant/<tenant_id>

Description: Update team details. Only OWNER or ADMIN can update team information.

Path Parameters:

• tenant_id (string, required) - Team ID

Request Body:

{
  "name": "string (optional, max 100 characters)",
  "llm_id": "string (optional, must be added by the user)",
  "embd_id": "string (optional, must be added by the user)",
  "asr_id": "string (optional, must be added by the user)",
  "img2txt_id": "string (optional, must be added by the user)",
  "rerank_id": "string (optional, must be added by the user)",
  "tts_id": "string (optional, must be added by the user)",
  "parser_ids": "string (optional)",
  "credit": "integer (optional)"
}

Response: Returns updated team information.

Status Codes:

• 200 - Team updated successfully
• 400 - Invalid request
• 401 - Unauthorized
• 403 - Forbidden - not owner or admin
• 404 - Team not found

---

3. Accept/Reject Team Invitation

Endpoint: PUT /tenant/update-request/<tenant_id>

Description: Accept or reject a team invitation. User must have INVITE role.

Path Parameters:

• tenant_id (string, required) - Team ID

Request Body:

{
  "accept": "boolean (required) - true to accept, false to reject",
  "role": "string (optional) - 'normal' or 'admin', only used when accept=true, defaults to 'normal'"
}

Response: Returns success status.

Status Codes:

• 200 - Invitation processed successfully
• 400 - Invalid request
• 401 - Unauthorized
• 404 - Invitation not found

---

4. Add Users to Team

Endpoint: POST /tenant/<tenant_id>/users/add

Description: Add one or more users directly to a team. Only OWNER or ADMIN can add users. Users are added immediately without requiring invitation acceptance. Supports both single user and bulk operations.

Path Parameters:

• tenant_id (string, required) - Team ID

Request Body:

{
  "users": [
    "string (email) or object with email and role",
    {
      "email": "string (required)",
      "role": "string (optional) - 'normal', 'admin', or 'invite', defaults to 'normal'"
    }
  ]
}

Response:

{
  "added": [
    {
      "id": "string",
      "email": "string",
      "nickname": "string",
      "avatar": "string",
      "role": "string"
    }
  ],
  "failed": [
    {
      "email": "string",
      "error": "string"
    }
  ]
}

Status Codes:

• 200 - Users added successfully (may include partial failures)
• 400 - Invalid request
• 401 - Unauthorized
• 403 - Forbidden - not owner or admin

---

5. Remove User from Team

Endpoint: POST /tenant/<tenant_id>/user/remove

Description: Remove a user from a team. Only OWNER or ADMIN can remove users. Owners cannot be removed.

Path Parameters:

• tenant_id (string, required) - Team ID

Request Body:

{
  "user_id": "string (required)"
}

Response:

{
  "user_id": "string",
  "email": "string"
}

Status Codes:

• 200 - User removed successfully
• 400 - Invalid request
• 401 - Unauthorized
• 403 - Forbidden - not owner or admin

---

6. Promote User to Admin

Endpoint: POST /tenant/<tenant_id>/admin/<user_id>/promote

Description: Promote a team member to admin role. Only team owners can promote members to admin. Cannot promote the team owner (owner role is permanent).

Path Parameters:

• tenant_id (string, required) - Team ID
• user_id (string, required) - User ID to promote to admin

Response: Returns success status and message.

Status Codes:

• 200 - User promoted to admin successfully
• 400 - Invalid request or user not found
• 401 - Unauthorized
• 403 - Forbidden - not team owner
• 404 - User not found in team

---

7. Demote Admin to Normal Member

Endpoint: POST /tenant/<tenant_id>/admin/<user_id>/demote

Description: Demote a team admin to normal member. Only team owners can demote admins. Cannot demote the team owner (owner role is permanent). Cannot demote yourself if you're the only admin/owner.

Path Parameters:

• tenant_id (string, required) - Team ID
• user_id (string, required) - User ID to demote from admin

Response: Returns success status and message.

Status Codes:

• 200 - Admin demoted to normal member successfully
• 400 - Invalid request or user not found
• 401 - Unauthorized
• 403 - Forbidden - not team owner
• 404 - User not found in team or not an admin

---

8. Get User Permissions

Endpoint: GET /tenant/<tenant_id>/users/<user_id>/permissions

Description: Get CRUD permissions for a team member. Only team owners or admins can view permissions.

Path Parameters:

• tenant_id (string, required) - Team ID
• user_id (string, required) - User ID to get permissions for

Response:

{
  "dataset": {
    "create": "boolean",
    "read": "boolean",
    "update": "boolean",
    "delete": "boolean"
  },
  "canvas": {
    "create": "boolean",
    "read": "boolean",
    "update": "boolean",
    "delete": "boolean"
  }
}

Status Codes:

• 200 - Permissions retrieved successfully
• 401 - Unauthorized
• 403 - Forbidden - not team owner or admin
• 404 - User not found in team

---

9. Update User Permissions

Endpoint: PUT /tenant/<tenant_id>/users/<user_id>/permissions

Description: Update CRUD permissions for a team member. Only team owners or admins can update permissions. Owners and admins always have full permissions and cannot be restricted.

Path Parameters:

• tenant_id (string, required) - Team ID
• user_id (string, required) - User ID to update permissions for

Request Body:

{
  "permissions": {
    "dataset": {
      "create": "boolean (optional)",
      "read": "boolean (optional)",
      "update": "boolean (optional)",
      "delete": "boolean (optional)"
    },
    "canvas": {
      "create": "boolean (optional)",
      "read": "boolean (optional)",
      "update": "boolean (optional)",
      "delete": "boolean (optional)"
    }
  }
}

Response: Returns updated permissions object.

Status Codes:

• 200 - Permissions updated successfully
• 400 - Invalid request
• 401 - Unauthorized
• 403 - Forbidden - not team owner or admin, or trying to restrict owner/admin
• 404 - User not found in team

---

User Management Endpoints

All user management endpoints are under the /user base path.

10. Create User

Endpoint: POST /user/create

Description: Create a new user. Requires authentication.

Request Body:

{
  "nickname": "string (required)",
  "email": "string (required, valid email format)",
  "password": "string (required, plain text or RSA-encrypted)",
  "is_superuser": "boolean (optional, default: false)"
}

Response: Returns created user information (id, email, nickname).

Status Codes:

• 200 - User created successfully
• 400 - Invalid request or email already exists
• 401 - Unauthorized - authentication required
• 500 - Server error during user creation

---

11. Update User

Endpoint: PUT /user/update

Description: Update an existing user. Users can only update their own account.

Request Body:

{
  "user_id": "string (optional, if email is provided)",
  "email": "string (optional, used to identify user or as new_email if user_id provided)",
  "new_email": "string (optional, new email address)",
  "nickname": "string (optional)",
  "password": "string (optional, encrypted)",
  "is_superuser": "boolean (optional)"
}

Response: Returns updated user information.

Status Codes:

• 200 - User updated successfully
• 400 - Invalid request or user not found
• 403 - Forbidden - users can only update their own account
• 500 - Server error during user update

---

12. List Users

Endpoint: GET /user/list

Description: List all users. Requires authentication. Supports pagination and email filtering.

Query Parameters:

• page (integer, optional) - Page number for pagination
• page_size (integer, optional) - Number of items per page
• email (string, optional) - Filter by email address

Response:

{
  "data": [
    {
      "id": "string",
      "email": "string",
      "nickname": "string",
      "is_superuser": "boolean"
    }
  ],
  "message": "string"
}

Status Codes:

• 200 - Users retrieved successfully
• 401 - Unauthorized - authentication required
• 500 - Server error during user listing

---

13. Delete User

Endpoint: DELETE /user/delete

Description: Delete a user. Users can only delete their own account. Requires authentication.

Request Body:

{
  "user_id": "string (optional, if email is provided)",
  "email": "string (optional, if user_id is provided)"
}

Response: Returns success status and message.

Status Codes:

• 200 - User deleted successfully
• 400 - Invalid request or user not found
• 401 - Unauthorized - authentication required
• 403 - Forbidden - users can only delete their own account
• 500 - Server error during user deletion

---

Summary

Total New Endpoints: 13

• Team Management: 9 endpoints
• User Management: 4 endpoints

All endpoints include proper authentication, authorization checks, input validation, and comprehensive error handling. The endpoints follow RESTful conventions and include detailed API documentation in their docstrings.

---

Canvas Authentication & Authorization

A comprehensive canvas permission system has been added to control access to canvases (agent canvases and dataflow canvases) within teams.

Canvas Permission Model

Canvases can be shared with teams using the following fields:

• permission: Can be "me" (private) or "team" (shared with team)
• shared_tenant_id: Optional field to specify which specific team the canvas is shared with (only used when permission is "team")

Canvas CRUD Permissions

Canvas permissions are managed through the same permission system as datasets. Each team member can have the following permissions for canvases:

• create: Create new team canvases
• read: View and run team canvases
• update: Modify team canvases
• delete: Delete team canvases

Permission Hierarchy

1. Canvas Owner: Always has full permissions (create, read, update, delete) on their own canvases
2. Team Owners & Admins: Always have full permissions on all team canvases
3. Normal Members: Permissions are controlled by the CRUD permissions set by team owners/admins (default: read-only)

Canvas Access Control

The UserCanvasService.accessible() method checks permissions before allowing canvas operations:

1. Ownership Check: If the user owns the canvas, access is always granted
2. Team Permission Check: If the canvas has permission="team", the system checks:
   • User is a member of the target team (either shared_tenant_id or canvas owner's team)
   • User has the required CRUD permission (create/read/update/delete) for that team
3. Private Canvas: If permission="me", only the owner can access it

Canvas Endpoints with Permission Checks

The following canvas endpoints now enforce permission checks:

1. GET /canvas/get/<canvas_id> - Requires read permission
2. POST /canvas/set - Requires create permission for new team canvases, update permission for existing canvases
3. POST /canvas/rm - Requires delete permission
4. POST /canvas/completion - Requires read permission (to run the canvas)
5. POST /canvas/reset - Requires update permission
6. POST /canvas/debug - Requires read permission

Canvas Sharing Workflow

1. Create Team Canvas:

   • User must have create permission in the target team
   • Set permission="team" and optionally shared_tenant_id to share with a specific team
   • If shared_tenant_id is not provided, canvas is shared with the owner's default team

2. Access Team Canvas:

   • User must be a member of the team the canvas is shared with
   • User must have appropriate CRUD permission (read to view, update to modify, etc.)

3. List Team Canvases:

   • Users see their own canvases plus team canvases they have access to
   • Filtering is based on team membership and shared_tenant_id

Integration with Team Permissions API

Canvas permissions are managed through the same endpoints as dataset permissions:

• GET /tenant/<tenant_id>/users/<user_id>/permissions - Returns canvas permissions along with dataset permissions
• PUT /tenant/<tenant_id>/users/<user_id>/permissions - Updates canvas permissions along with dataset permissions

Example permissions structure:

{
  "dataset": {
    "create": false,
    "read": true,
    "update": false,
    "delete": false
  },
  "canvas": {
    "create": true,
    "read": true,
    "update": true,
    "delete": false
  }
}

---

Notes

• All endpoints require authentication unless otherwise specified
• Team endpoints use role-based access control (OWNER, ADMIN, NORMAL, INVITE)
• User endpoints allow users to manage only their own accounts
• All endpoints return consistent JSON response format with data, message, and code fields
• Model IDs must be added by the user before they can be used in team creation/updates
• Permissions system supports CRUD operations on datasets and canvases
• Canvas permissions are enforced at the API level for all canvas operations
• Canvas owners always have full permissions on their own canvases, regardless of team permissions
• Team owners and admins always have full permissions on all team canvases

Type of change

• Bug Fix (non-breaking change which fixes an issue)
• New Feature (non-breaking change which adds functionality)
• Documentation Update
• Refactoring
• Performance Improvement
• Other (please describe):

[yingfeng]

Thanks for the contribution, could you please fix the CI at first ?