Skip to main content

​
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.
​
body
object

​
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.
​
body
object

​
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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
  "role": "MEMBER",
  "message": "Welcome to our team! We're excited to have you join us."
}

{
  "success": true,
  "invitation": {
    "id": "inv_789",
    "email": "[email protected]",
    "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.
​
body
object

​
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": "[email protected]",
    "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.
​
body
object

​
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:
1

OWNER

Full control over organization including deletion and billing
2

ADMIN

Can manage members, update organization settings, access billing
3

MEMBER

Can create and manage campaigns, leads, and content
4

VIEWER

Read-only access to organization data

​
Permission Matrix

ActionOWNERADMINMEMBERVIEWER
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:
  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