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

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"
}

{
  "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"
}

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

object

Show Request Body

string

required

Organization name (2-100 characters)

string

Organization description (optional)

string

Organization website URL (optional)

string

Industry category (optional)

string

Organization size range (optional)

Get All Organizations

GET /organizations
Authorization: Bearer <token>

{
  "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"
}

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

Get Organization Details

GET /organizations/org_abc123
Authorization: Bearer <token>

{
  "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"
}

Description: Retrieves detailed information about a specific organization.

Update Organization

PATCH /organizations/org_abc123
Authorization: Bearer <token>
Content-Type: application/json

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

{
  "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"
}

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

object

Show Request Body

string

Organization name (optional)

string

Organization description (optional)

string

Organization website URL (optional)

string

Industry category (optional)

string

Organization size range (optional)

Delete Organization

DELETE /organizations/org_abc123
Authorization: Bearer <token>

{
  "success": true,
  "message": "Organization deleted successfully"
}

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

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

Member Management

Get Organization Members

GET /organizations/org_abc123/members
Authorization: Bearer <token>

{
  "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"
}

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

Invite User to Organization

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."
}

{
  "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"
}

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

object

Show Request Body

string

required

Email address of the user to invite

string

required

Role to assign (OWNER, ADMIN, MEMBER, VIEWER)

string

Personal message to include in the invitation email

Update Member Role

PATCH /organizations/org_abc123/members/usr_456/role
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "ADMIN"
}

{
  "success": true,
  "member": {
    "id": "usr_456",
    "email": "jane@acme.com",
    "role": "ADMIN",
    "updatedAt": "2024-01-20T15:30:00Z"
  },
  "message": "Member role updated successfully"
}

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

object

Show Request Body

string

required

New role (OWNER, ADMIN, MEMBER, VIEWER)

Remove Member

DELETE /organizations/org_abc123/members/usr_456
Authorization: Bearer <token>

{
  "success": true,
  "message": "Member removed from organization successfully"
}

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

Leave Organization

DELETE /organizations/org_abc123/members/leave
Authorization: Bearer <token>

{
  "success": true,
  "message": "Successfully left organization"
}

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

Role Hierarchy

The VChata platform uses a hierarchical role system:

OWNER

Full control over organization including deletion and billing

ADMIN

Can manage members, update organization settings, access billing

MEMBER

Can create and manage campaigns, leads, and content

VIEWER

Read-only access to organization data

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

{
  "success": false,
  "statusCode": 403,
  "message": "Only owners and admins can invite members",
  "error": "Forbidden"
}

{
  "success": false,
  "statusCode": 404,
  "message": "Organization not found or you don't have access",
  "error": "Not Found"
}

{
  "success": false,
  "statusCode": 409,
  "message": "User is already a member of this organization",
  "error": "Conflict"
}

{
  "success": false,
  "statusCode": 400,
  "message": [
    "email must be an email",
    "role must be one of: OWNER, ADMIN, MEMBER, VIEWER"
  ],
  "error": "Bad Request"
}

Organization Switching

Users can belong to multiple organizations and switch between them:

Multi-Organization Support - Users can be members of multiple organizations
Context Switching - Frontend can switch organization context
Scoped Operations - All operations are scoped to the current organization
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

Getting Started

Authentication

Core Services

Content & Social

AI & Automation

Analytics & Insights

Communication

Utilities

Services

Organizations Controller

Organizations Controller

Base Path

Overview

Authentication & Authorization

Organization Management

Create Organization

Get All Organizations

Get Organization Details

Update Organization

Delete Organization

Member Management

Get Organization Members

Invite User to Organization

Update Member Role

Remove Member

Leave Organization

Role Hierarchy

Permission Matrix

Error Responses

Common Errors

Organization Switching

Security Features

​Organizations Controller

​Base Path

​Overview

​Authentication & Authorization

​Organization Management

​Create Organization

​Get All Organizations

​Get Organization Details

​Update Organization

​Delete Organization

​Member Management

​Get Organization Members

​Invite User to Organization

​Update Member Role

​Remove Member

​Leave Organization

​Role Hierarchy

​Permission Matrix

​Error Responses

​Common Errors

​Organization Switching

​Security Features

Organizations Controller

Base Path

Overview

Authentication & Authorization

Organization Management

Create Organization

Get All Organizations

Get Organization Details

Update Organization

Delete Organization

Member Management

Get Organization Members

Invite User to Organization

Update Member Role

Remove Member

Leave Organization

Role Hierarchy

Permission Matrix

Error Responses

Common Errors

Organization Switching

Security Features