> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Team Members & RBAC

> Manage workspace members and role-based access control

Team members and role-based access control (RBAC) enables workspace collaboration with granular permission management.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Workspace Team Management"
        A[👥 Add Member] --> B[🔒 Assign Role]
        B --> C[⚙️ Manage Permissions]
        C --> D[📊 Monitor Access]
    end
    
    classDef member fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef role fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef permission fill:#10B981,stroke:#7C90A0,color:#fff
    classDef monitor fill:#8B0000,stroke:#7C90A0,color:#fff
    
    class A member
    class B role
    class C permission
    class D monitor
```

## Quick Start

<Steps>
  <Step title="Add a Member">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Add a member with basic member role
    curl -X POST http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"user_id":"user-abc123","role":"member"}'
    ```
  </Step>

  <Step title="Update Member Role">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Promote member to admin
    curl -X PATCH http://localhost:8000/api/v1/workspaces/{workspace_id}/members/{user_id} \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"role":"admin"}'
    ```
  </Step>

  <Step title="List All Members">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # View all workspace members
    curl http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Owner as 👑 Owner
    participant API as 🔌 Platform API
    participant Member as 👤 New Member
    
    Owner->>API: Add Member Request
    API->>API: Validate Permissions
    API->>Member: Send Invitation
    Member->>API: Accept Invitation
    API-->>Owner: Member Added Successfully
```

| Role       | Add Members | Manage Settings | Create Issues | Remove Members |
| ---------- | ----------- | --------------- | ------------- | -------------- |
| **Owner**  | ✅           | ✅               | ✅             | ✅              |
| **Admin**  | ✅           | ✅               | ✅             | ✅              |
| **Member** | ❌           | ❌               | ✅             | ❌              |

***

## API Endpoints

### Add Member

Add a new member to the workspace with a specific role.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl -X POST http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": "user-abc123",
      "role": "member"
    }'
  ```

  ```python Python SDK theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import asyncio
  from praisonai_platform.client import PlatformClient

  async def add_member():
      client = PlatformClient("http://localhost:8000", token="your-jwt-token")
      
      member = await client.add_member(
          workspace_id="ws-abc123",
          user_id="user-abc123",
          role="member"
      )
      print(f"Added member: {member['user_id']} as {member['role']}")

  asyncio.run(add_member())
  ```
</CodeGroup>

### List Members

Retrieve all members in the workspace.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```python Python SDK theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import asyncio
  from praisonai_platform.client import PlatformClient

  async def list_members():
      client = PlatformClient("http://localhost:8000", token="your-jwt-token")
      
      members = await client.list_members("ws-abc123")
      for member in members:
          print(f"{member['user_id']}: {member['role']}")

  asyncio.run(list_members())
  ```
</CodeGroup>

### Update Member Role

Change a member's role within the workspace.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl -X PATCH http://localhost:8000/api/v1/workspaces/{workspace_id}/members/{user_id} \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "role": "admin"
    }'
  ```

  ```python Python SDK theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import asyncio
  from praisonai_platform.client import PlatformClient

  async def update_role():
      client = PlatformClient("http://localhost:8000", token="your-jwt-token")
      
      member = await client.update_member_role(
          workspace_id="ws-abc123",
          user_id="user-abc123",
          role="admin"
      )
      print(f"Updated {member['user_id']} to {member['role']}")

  asyncio.run(update_role())
  ```
</CodeGroup>

### Remove Member

Remove a member from the workspace.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl -X DELETE http://localhost:8000/api/v1/workspaces/{workspace_id}/members/{user_id} \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```python Python SDK theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import asyncio
  from praisonai_platform.client import PlatformClient

  async def remove_member():
      client = PlatformClient("http://localhost:8000", token="your-jwt-token")
      
      await client.remove_member(
          workspace_id="ws-abc123",
          user_id="user-abc123"
      )
      print("Member removed successfully")

  asyncio.run(remove_member())
  ```
</CodeGroup>

***

## Role Hierarchy

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Role Hierarchy"
        Owner[👑 Owner<br/>Full Control]
        Admin[🔧 Admin<br/>Management Access]
        Member[👤 Member<br/>Basic Access]
    end
    
    Owner --> Admin
    Admin --> Member
    
    classDef owner fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef admin fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef member fill:#10B981,stroke:#7C90A0,color:#fff
    
    class Owner owner
    class Admin admin
    class Member member
```

### Role Capabilities

| Capability                | Owner | Admin | Member |
| ------------------------- | ----- | ----- | ------ |
| **Member Management**     |       |       |        |
| Add members               | ✅     | ✅     | ❌      |
| Remove members            | ✅     | ✅     | ❌      |
| Update member roles       | ✅     | ✅     | ❌      |
| **Workspace Settings**    |       |       |        |
| Modify workspace settings | ✅     | ✅     | ❌      |
| Delete workspace          | ✅     | ❌     | ❌      |
| **Content Management**    |       |       |        |
| Create issues/tasks       | ✅     | ✅     | ✅      |
| Edit own content          | ✅     | ✅     | ✅      |
| Edit others' content      | ✅     | ✅     | ❌      |

***

## Schema Reference

### Add Member Request

| Field     | Type     | Required | Description                                   |
| --------- | -------- | -------- | --------------------------------------------- |
| `user_id` | `string` | ✅        | Unique identifier for the user                |
| `role`    | `string` | ✅        | Role to assign: `owner`, `admin`, or `member` |

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "user_id": "user-abc123",
  "role": "member"
}
```

### Update Role Request

| Field  | Type     | Required | Description                             |
| ------ | -------- | -------- | --------------------------------------- |
| `role` | `string` | ✅        | New role: `owner`, `admin`, or `member` |

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "role": "admin"
}
```

### Member Response

| Field          | Type     | Description          |
| -------------- | -------- | -------------------- |
| `id`           | `string` | Unique member ID     |
| `workspace_id` | `string` | Workspace identifier |
| `user_id`      | `string` | User identifier      |
| `role`         | `string` | Current role         |
| `created_at`   | `string` | ISO 8601 timestamp   |

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "id": "mem-abc123",
  "workspace_id": "ws-abc123",
  "user_id": "user-abc123",
  "role": "admin",
  "created_at": "2025-01-01T00:00:00"
}
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Principle of Least Privilege">
    Always assign the minimum role required for a user's responsibilities. Start with `member` role and promote only when necessary for their workspace functions.
  </Accordion>

  <Accordion title="Regular Role Audits">
    Periodically review member roles and permissions. Remove inactive members and adjust roles based on changing responsibilities within the workspace.
  </Accordion>

  <Accordion title="Owner Role Management">
    Limit the number of owners in a workspace. Having too many owners can create security risks and confusion about who has ultimate responsibility.
  </Accordion>

  <Accordion title="Secure Token Management">
    Always use secure JWT tokens for API authentication. Store tokens securely and rotate them regularly to maintain workspace security.
  </Accordion>
</AccordionGroup>

***

## Testing

Run the member management tests to verify functionality:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pytest tests/test_services.py::TestMemberService -v
```

Expected test coverage includes:

* Adding members with different roles
* Role hierarchy validation
* Permission enforcement
* Member removal workflows

***

## Related

<CardGroup cols={2}>
  <Card title="Workspace Management" icon="building" href="/docs/features/workspace-management">
    Learn about workspace creation and management
  </Card>

  <Card title="Authentication" icon="key" href="/docs/features/authentication">
    Understand JWT token authentication
  </Card>
</CardGroup>