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

# Organizations Controller

> Organization management and team collaboration API endpoints

# Organizations Controller

The Organizations Controller provides comprehensive organization management capabilities including creation, member management, role-based access control, and team collaboration features for the VChata platform.

## Base Path

```
/organizations
```

## Overview

This controller enables multi-tenant organization management with:

* 🏢 **Organization Management** - Create, update, and delete organizations
* 👥 **Member Management** - Invite, remove, and manage team members
* 🔐 **Role-Based Access** - OWNER, ADMIN, MEMBER, and VIEWER roles
* 📧 **Invitation System** - Email-based user invitations
* 🔄 **Organization Switching** - Multi-organization support for users
* 🛡️ **Permission Control** - Granular access control for all operations

## Authentication & Authorization

* 🔐 All endpoints require valid JWT authentication token
* 👥 Role-based access control (OWNER > ADMIN > MEMBER > VIEWER)
* 🏢 Organization-scoped operations with membership verification
* 🛡️ Guards ensure users can only access organizations they belong to

## Organization Management

### Create Organization

<RequestExample>
  ```http theme={null}
  POST /organizations
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "name": "Acme Corporation",
    "description": "Leading AI automation company",
    "website": "https://acme.com",
    "industry": "Technology",
    "size": "50-100"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "organization": {
      "id": "org_abc123",
      "name": "Acme Corporation",
      "description": "Leading AI automation company",
      "website": "https://acme.com",
      "industry": "Technology",
      "size": "50-100",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z",
      "memberCount": 1,
      "role": "OWNER"
    },
    "message": "Organization created successfully"
  }
  ```
</ResponseExample>

**Description**: Creates a new organization with the current user as the owner.

<ParamField path="body" type="object">
  <Expandable title="Request Body">
    <ParamField path="name" type="string" required>
      Organization name (2-100 characters)
    </ParamField>

    <ParamField path="description" type="string">
      Organization description (optional)
    </ParamField>

    <ParamField path="website" type="string">
      Organization website URL (optional)
    </ParamField>

    <ParamField path="industry" type="string">
      Industry category (optional)
    </ParamField>

    <ParamField path="size" type="string">
      Organization size range (optional)
    </ParamField>
  </Expandable>
</ParamField>

### Get All Organizations

<RequestExample>
  ```http theme={null}
  GET /organizations
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "organizations": [
      {
        "id": "org_abc123",
        "name": "Acme Corporation",
        "description": "Leading AI automation company",
        "website": "https://acme.com",
        "createdAt": "2024-01-15T10:00:00Z",
        "memberCount": 5,
        "role": "OWNER"
      },
      {
        "id": "org_def456",
        "name": "Beta Inc",
        "description": "Innovation lab",
        "createdAt": "2024-02-01T14:30:00Z",
        "memberCount": 12,
        "role": "ADMIN"
      }
    ],
    "total": 2,
    "message": "Organizations retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves all organizations the current user belongs to with their roles.

### Get Organization Details

<RequestExample>
  ```http theme={null}
  GET /organizations/org_abc123
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "organization": {
      "id": "org_abc123",
      "name": "Acme Corporation",
      "description": "Leading AI automation company",
      "website": "https://acme.com",
      "industry": "Technology",
      "size": "50-100",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-20T15:30:00Z",
      "memberCount": 5,
      "role": "OWNER",
      "settings": {
        "allowMemberInvites": true,
        "requireApprovalForJoins": false,
        "defaultRole": "MEMBER"
      }
    },
    "message": "Organization retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves detailed information about a specific organization.

### Update Organization

<RequestExample>
  ```http theme={null}
  PATCH /organizations/org_abc123
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "name": "Acme Corp Updated",
    "description": "Updated description",
    "website": "https://newacme.com"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "organization": {
      "id": "org_abc123",
      "name": "Acme Corp Updated",
      "description": "Updated description",
      "website": "https://newacme.com",
      "updatedAt": "2024-01-20T15:30:00Z"
    },
    "message": "Organization updated successfully"
  }
  ```
</ResponseExample>

**Description**: Updates organization details. Requires OWNER or ADMIN role.

<ParamField path="body" type="object">
  <Expandable title="Request Body">
    <ParamField path="name" type="string">
      Organization name (optional)
    </ParamField>

    <ParamField path="description" type="string">
      Organization description (optional)
    </ParamField>

    <ParamField path="website" type="string">
      Organization website URL (optional)
    </ParamField>

    <ParamField path="industry" type="string">
      Industry category (optional)
    </ParamField>

    <ParamField path="size" type="string">
      Organization size range (optional)
    </ParamField>
  </Expandable>
</ParamField>

### Delete Organization

<RequestExample>
  ```http theme={null}
  DELETE /organizations/org_abc123
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Organization deleted successfully"
  }
  ```
</ResponseExample>

**Description**: Permanently deletes an organization. Requires OWNER role only.

<Warning>
  **Irreversible Action**: Deleting an organization will permanently remove all associated data including campaigns, leads, billing information, and member access.
</Warning>

## Member Management

### Get Organization Members

<RequestExample>
  ```http theme={null}
  GET /organizations/org_abc123/members
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "members": [
      {
        "id": "usr_123",
        "email": "john@acme.com",
        "firstName": "John",
        "lastName": "Doe",
        "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=john",
        "role": "OWNER",
        "joinedAt": "2024-01-15T10:00:00Z",
        "lastActiveAt": "2024-01-20T15:30:00Z",
        "status": "active"
      },
      {
        "id": "usr_456",
        "email": "jane@acme.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=jane",
        "role": "ADMIN",
        "joinedAt": "2024-01-16T09:00:00Z",
        "lastActiveAt": "2024-01-20T14:00:00Z",
        "status": "active"
      }
    ],
    "total": 2,
    "message": "Members retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves all members of the organization with their roles and activity status.

### Invite User to Organization

<RequestExample>
  ```http theme={null}
  POST /organizations/org_abc123/members/invite
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "email": "newuser@acme.com",
    "role": "MEMBER",
    "message": "Welcome to our team! We're excited to have you join us."
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "invitation": {
      "id": "inv_789",
      "email": "newuser@acme.com",
      "role": "MEMBER",
      "invitedBy": "usr_123",
      "invitedAt": "2024-01-20T15:30:00Z",
      "status": "pending",
      "expiresAt": "2024-01-27T15:30:00Z"
    },
    "message": "Invitation sent successfully"
  }
  ```
</ResponseExample>

**Description**: Sends an invitation email to join the organization. Requires OWNER or ADMIN role.

<ParamField path="body" type="object">
  <Expandable title="Request Body">
    <ParamField path="email" type="string" required>
      Email address of the user to invite
    </ParamField>

    <ParamField path="role" type="string" required>
      Role to assign (OWNER, ADMIN, MEMBER, VIEWER)
    </ParamField>

    <ParamField path="message" type="string">
      Personal message to include in the invitation email
    </ParamField>
  </Expandable>
</ParamField>

### Update Member Role

<RequestExample>
  ```http theme={null}
  PATCH /organizations/org_abc123/members/usr_456/role
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "role": "ADMIN"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "member": {
      "id": "usr_456",
      "email": "jane@acme.com",
      "role": "ADMIN",
      "updatedAt": "2024-01-20T15:30:00Z"
    },
    "message": "Member role updated successfully"
  }
  ```
</ResponseExample>

**Description**: Updates a member's role in the organization. Requires OWNER or ADMIN role.

<ParamField path="body" type="object">
  <Expandable title="Request Body">
    <ParamField path="role" type="string" required>
      New role (OWNER, ADMIN, MEMBER, VIEWER)
    </ParamField>
  </Expandable>
</ParamField>

### Remove Member

<RequestExample>
  ```http theme={null}
  DELETE /organizations/org_abc123/members/usr_456
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Member removed from organization successfully"
  }
  ```
</ResponseExample>

**Description**: Removes a member from the organization. Requires OWNER or ADMIN role.

### Leave Organization

<RequestExample>
  ```http theme={null}
  DELETE /organizations/org_abc123/members/leave
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Successfully left organization"
  }
  ```
</ResponseExample>

**Description**: Allows the current user to leave the organization (self-removal).

## Role Hierarchy

The VChata platform uses a hierarchical role system:

<Steps>
  <Step title="OWNER">
    Full control over organization including deletion and billing
  </Step>

  <Step title="ADMIN">
    Can manage members, update organization settings, access billing
  </Step>

  <Step title="MEMBER">
    Can create and manage campaigns, leads, and content
  </Step>

  <Step title="VIEWER">
    Read-only access to organization data
  </Step>
</Steps>

## Permission Matrix

| Action              | OWNER | ADMIN | MEMBER | VIEWER |
| ------------------- | ----- | ----- | ------ | ------ |
| Delete Organization | ✅     | ❌     | ❌      | ❌      |
| Update Organization | ✅     | ✅     | ❌      | ❌      |
| Invite Members      | ✅     | ✅     | ❌      | ❌      |
| Update Member Roles | ✅     | ✅     | ❌      | ❌      |
| Remove Members      | ✅     | ✅     | ❌      | ❌      |
| Access Billing      | ✅     | ✅     | ❌      | ❌      |
| Create Campaigns    | ✅     | ✅     | ✅      | ❌      |
| View Analytics      | ✅     | ✅     | ✅      | ✅      |

## Error Responses

### Common Errors

<ResponseExample status="403">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 403,
    "message": "Only owners and admins can invite members",
    "error": "Forbidden"
  }
  ```
</ResponseExample>

<ResponseExample status="404">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 404,
    "message": "Organization not found or you don't have access",
    "error": "Not Found"
  }
  ```
</ResponseExample>

<ResponseExample status="409">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 409,
    "message": "User is already a member of this organization",
    "error": "Conflict"
  }
  ```
</ResponseExample>

<ResponseExample status="400">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 400,
    "message": [
      "email must be an email",
      "role must be one of: OWNER, ADMIN, MEMBER, VIEWER"
    ],
    "error": "Bad Request"
  }
  ```
</ResponseExample>

## Organization Switching

Users can belong to multiple organizations and switch between them:

1. **Multi-Organization Support** - Users can be members of multiple organizations
2. **Context Switching** - Frontend can switch organization context
3. **Scoped Operations** - All operations are scoped to the current organization
4. **Role Preservation** - User roles are maintained per organization

## Security Features

* 🔐 **JWT Authentication** - All endpoints require valid authentication
* 🛡️ **Organization Guards** - Ensures users can only access their organizations
* 👥 **Role-Based Access** - Granular permissions based on user roles
* 📧 **Secure Invitations** - Email-based invitations with expiration
* 🔄 **Audit Trail** - All member actions are logged
* 🚫 **Self-Protection** - Owners cannot remove themselves without transferring ownership