Organizations

Overview

CloudWA is multi-tenant — each organization has its own isolated data (contacts, conversations, templates, etc.). Users can belong to multiple organizations with different roles in each.

List Organizations

Retrieve all organizations. Requires super admin or organizations:read permission.

GET /api/organizations

Response

{
  "status": "success",
  "data": {
    "organizations": [
      {
        "id": "uuid",
        "name": "Acme Corp",
        "slug": "acme-corp-a1b2c3d4",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Current Organization

Retrieve the current organization’s details.

GET /api/organizations/current

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Acme Corp",
    "slug": "acme-corp-a1b2c3d4",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Create Organization

Create a new organization. The creator is automatically added as an admin. System roles (Admin, Manager, Agent) and default chatbot settings are seeded automatically.

POST /api/organizations

Note

Requires organizations:write permission.

Request Body

{
  "name": "New Organization"
}

Field	Type	Required	Description
name	string	Yes	Organization name

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "New Organization",
    "slug": "new-organization-a1b2c3d4",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Organization Members

Manage which users have access to an organization. Members are users from other organizations who have been granted access with a specific role.

List Members

Retrieve all members of the current organization.

GET /api/organizations/members

Note

Requires organizations:read permission.

Query Parameters

Parameter	Type	Description
search	string	Filter by name or email
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50)

Response

{
  "status": "success",
  "data": {
    "members": [
      {
        "id": "uuid",
        "user_id": "uuid",
        "organization_id": "uuid",
        "role_id": "uuid",
        "role_name": "agent",
        "is_default": true,
        "email": "user@example.com",
        "full_name": "John Doe",
        "is_active": true,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

Add Member

Add an existing user to the organization. The user can be identified by user_id or email.

POST /api/organizations/members

Note

Requires organizations:assign permission.

Request Body

{
  "user_id": "uuid",
  "role_id": "uuid"
}

Or by email:

{
  "email": "user@example.com",
  "role_id": "uuid"
}

Field	Type	Required	Description
user_id	string	One of user_id or email	UUID of the user to add
email	string	One of user_id or email	Email of the user to add
role_id	string	No	Role to assign. If omitted, uses the organization’s default role

Response

{
  "status": "success",
  "data": {
    "message": "Member added successfully"
  }
}

Update Member Role

Change a member’s role within the organization.

PUT /api/organizations/members/{member_id}

Note

Requires organizations:assign permission. The member_id is the user’s UUID.

Request Body

{
  "role_id": "uuid"
}

Response

{
  "status": "success",
  "data": {
    "message": "Member role updated successfully"
  }
}

Remove Member

Remove a user from the organization. This only removes the membership — the user’s account remains intact.

DELETE /api/organizations/members/{member_id}

Note

Requires organizations:assign permission.

Caution

You cannot remove yourself from the organization.

Response

{
  "status": "success",
  "data": {
    "message": "Member removed successfully"
  }
}

Organization Settings

Get Settings

GET /api/org/settings

Response

{
  "status": "success",
  "data": {
    "name": "Acme Corp",
    "settings": {
      "mask_phone_numbers": false,
      "timezone": "UTC",
      "date_format": "YYYY-MM-DD",
      "calling_enabled": true,
      "max_call_duration": 3600,
      "transfer_timeout_secs": 60,
      "hold_music_file": "org_uuid_hold_music.ogg",
      "ringback_file": "org_uuid_ringback.ogg"
    }
  }
}

Update Settings

PUT /api/org/settings

Request Body

{
  "name": "Updated Name",
  "mask_phone_numbers": true,
  "timezone": "Asia/Kolkata",
  "date_format": "DD/MM/YYYY",
  "calling_enabled": true,
  "max_call_duration": 3600,
  "transfer_timeout_secs": 60
}

All fields are optional — only provided fields are updated.

Response

{
  "status": "success",
  "data": {
    "message": "Settings updated successfully"
  }
}

Upload Organization Audio

Upload audio files for organization hold music or ringback tones.

POST /api/org/audio?type=hold_music

Query Parameters

Parameter	Type	Required	Description
type	string	Yes	The type of audio: hold_music or ringback

Request Body

A multipart/form-data request containing:

• file: The audio file to upload (maximum size is 5MB). Supported formats: OGG, Opus, MP3, WAV, AAC, M4A.

Response

{
  "status": "success",
  "data": {
    "filename": "org_uuid_hold_music.ogg",
    "type": "hold_music",
    "mime_type": "audio/mpeg",
    "size": 1048576
  }
}

Single Sign-On (SSO) Settings

Configure external identity providers for Single Sign-On (SSO) login.

Get SSO Settings

Retrieve all configured SSO providers for the organization.

GET /api/settings/sso

Response

{
  "status": "success",
  "data": [
    {
      "provider": "google",
      "client_id": "google-client-id",
      "has_secret": true,
      "is_enabled": true,
      "allow_auto_create": true,
      "default_role": "agent",
      "allowed_domains": "example.com"
    }
  ]
}

Update SSO Provider Config

Create or update the configuration for a specific SSO provider.

PUT /api/settings/sso/{provider}

Path Parameters

Parameter	Type	Required	Description
provider	string	Yes	The provider type: google, microsoft, github, facebook, or custom

Request Body

{
  "client_id": "client-id",
  "client_secret": "client-secret",
  "is_enabled": true,
  "allow_auto_create": true,
  "default_role": "agent",
  "allowed_domains": "example.com",
  "auth_url": "https://example.com/oauth/authorize",
  "token_url": "https://example.com/oauth/token",
  "user_info_url": "https://example.com/oauth/userinfo"
}

Field	Type	Required	Description
client_id	string	Yes	The OAuth2 client ID
client_secret	string	No	The OAuth2 client secret (omitted if not changing)
is_enabled	boolean	Yes	Enable or disable this provider
allow_auto_create	boolean	Yes	Auto-create user accounts on successful login if they do not exist
default_role	string	No	The default role assigned to auto-created users (defaults to agent)
allowed_domains	string	No	Comma-separated list of email domains allowed to log in (empty allows all)
auth_url	string	No	Authorization URL (required only for custom provider)
token_url	string	No	Token URL (required only for custom provider)
user_info_url	string	No	User info endpoint URL (required only for custom provider)

Response

{
  "status": "success",
  "data": {
    "provider": "google",
    "client_id": "google-client-id",
    "has_secret": true,
    "is_enabled": true,
    "allow_auto_create": true,
    "default_role": "agent",
    "allowed_domains": "example.com"
  }
}

Delete SSO Provider

Delete/remove the SSO configuration for a specific provider.

DELETE /api/settings/sso/{provider}

Path Parameters

Parameter	Type	Required	Description
provider	string	Yes	The provider type: google, microsoft, github, facebook, or custom

Response

{
  "status": "success",
  "data": {
    "message": "SSO provider deleted"
  }
}

See Also

• Authentication - Organization switching via POST /api/auth/switch-org
• Users - User management within an organization
• Roles & Permissions - Permission system details