Organizations

Organizations are the top-level entities in Taruvi Cloud that group users, sites, and resources together. They provide a way to manage teams and their associated cloud environments.

Slug-Based URLs

All organization endpoints now use slug-based URLs (e.g., /api/cloud/organizations/acme-corp/) instead of UUID-based URLs. Slugs are human-readable, SEO-friendly identifiers automatically generated from the organization name. UUIDs are still supported for backward compatibility.

Overview

An organization represents a company, team, or any group of users working together. Each organization can have:

• Multiple members with different roles and permissions
• Multiple sites (cloud environments/tenants)
• Custom settings and configurations
• Invitations to onboard new members

Key Features

Multi-Tenant Structure

Organizations enable multi-tenant SaaS architecture where:

• Each organization is isolated from others
• Resources (sites, users, data) are scoped to organizations
• Cross-organization data access is prevented

Role-Based Access

Organizations support fine-grained permission management:

• Owner: Full control over the organization
• Members: Can be assigned specific permissions
• Custom Permissions: view_organization, change_organization, delete_organization, manage_organization, invite_members

Member Management

• Add and remove members
• Assign permissions to members
• Track member activity and roles
• Invite new members via email

Using Organizations

Creating an Organization

To create a new organization:

POST /api/cloud/organizations/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Acme Corporation",
  "slug": "acme-corp"
}

Response:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "is_active": true,
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-15T10:30:00Z"
}

Listing Organizations

Get all organizations you have access to:

GET /api/cloud/organizations/
Authorization: Bearer YOUR_ACCESS_TOKEN

Query Parameters:

• search: Search by name or slug
• is_active: Filter by active status
  • true or 1: Only active organizations (default)
  • false or 0: Only inactive organizations
  • all or *: All organizations regardless of status
• ordering: Sort results (e.g., name, -created, modified)

Retrieving Organization Details

Get details of a specific organization:

GET /api/cloud/organizations/{slug}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/organizations/acme-corp/

Updating an Organization

Update organization details:

PUT /api/cloud/organizations/{slug}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Acme Corporation Ltd",
  "is_active": true
}

Example:

PUT /api/cloud/organizations/acme-corp/

Deleting an Organization

Delete an organization permanently:

DELETE /api/cloud/organizations/{slug}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

DELETE /api/cloud/organizations/acme-corp/

Permanent Deletion

Organization deletion is permanent (hard delete) and triggers the following cascade:

• All organization memberships are removed
• All invitations are deleted
• All sites belonging only to this organization are deleted (including their PostgreSQL schemas)
• All domains linked to those sites are deleted
• All Guardian permissions for the organization are removed
• Users who are not members of any other organization are soft-deleted (marked inactive)

Managing Members

Adding Members

Add a user to an organization:

POST /api/cloud/organizations/{org_slug}/members/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "user_slug": "john-doe"
}

Example:

POST /api/cloud/organizations/acme-corp/members/
{
  "user_slug": "jane-smith"
}

Listing Members

Get all members of an organization:

GET /api/cloud/organizations/{org_slug}/members/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/organizations/acme-corp/members/

Retrieving Member Details

Get details of a specific member including their groups and site permissions:

GET /api/cloud/organizations/{org_slug}/members/{username}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/organizations/acme-corp/members/john.doe/

Response:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "john.doe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "is_admin": false,
  "is_owner": false,
  "groups": [
    {
      "id": 1,
      "name": "Developers"
    }
  ],
  "sites": [
    {
      "uuid": "750e8400-e29b-41d4-a716-446655440000",
      "name": "Production Site",
      "schema_name": "production_site",
      "permissions": ["access_site", "view_site", "manage_site"]
    }
  ]
}

Updating Member Permissions

Update a member's groups and site permissions:

PUT /api/cloud/organizations/{org_slug}/members/{username}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "is_admin": false,
  "groups": [1, 2],
  "site": [
    {
      "uuid": "750e8400-e29b-41d4-a716-446655440000",
      "permissions": ["access_site", "view_site", "manage_site"]
    }
  ]
}

Example:

PUT /api/cloud/organizations/acme-corp/members/john.doe/
{
  "groups": [1, 3],
  "site": [
    {
      "uuid": "site-uuid",
      "permissions": ["access_site", "manage_site"]
    }
  ]
}

Managing Admin Status

Make a member an admin:

POST /api/cloud/organizations/{org_slug}/members/{username}/make_admin/
Authorization: Bearer YOUR_ACCESS_TOKEN

Remove admin status:

POST /api/cloud/organizations/{org_slug}/members/{username}/remove_admin/
Authorization: Bearer YOUR_ACCESS_TOKEN

warning

You cannot remove admin status from the last admin of an organization. There must always be at least one admin.

Removing Members

Remove a member from an organization:

DELETE /api/cloud/organizations/{org_slug}/members/{username}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

DELETE /api/cloud/organizations/acme-corp/members/jane.smith/

Checking Your Permissions

Get your effective permissions within an organization:

GET /api/cloud/organizations/{org_slug}/privileges/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/organizations/acme-corp/privileges/

Response:

{
  "permissions": [
    "view_organization",
    "change_organization",
    "manage_organization",
    "invite_members",
    "manage_sites"
  ]
}

This endpoint returns all permissions you have on the specified organization, including permissions inherited from groups.

Managing Invitations

Invitations allow you to onboard new members to your organization with pre-configured access levels, groups, and site permissions.

Quick Start

Send a basic invitation:

POST /api/cloud/organizations/acme-corp/invitations/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "invitee_identifier": "newuser@acme.com"
}

Send an invitation with permissions:

POST /api/cloud/organizations/acme-corp/invitations/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "invitee_identifier": "newuser@acme.com",
  "invitation_config": {
    "group": [3],
    "site": [
      {
        "slug": "production-site",
        "permissions": ["view_site", "manage_site"]
      }
    ]
  }
}

What the invitation config does:

• group: Assigns user to specified groups (by ID) upon acceptance
• site: Grants site-specific permissions upon acceptance

Public Invitation URLs

Invitees can accept invitations without authentication using public URLs:

GET  /api/cloud/invitations/{token}/details/  (View invitation)
POST /api/cloud/invitations/{token}/accept/   (Accept invitation)

These endpoints are unauthenticated and accessible by anyone with the invitation token.

Comprehensive Documentation

For detailed invitation workflows, permission configuration, and public acceptance APIs, see the Invitations Guide.

Common Operations

List invitations:

GET /api/cloud/organizations/acme-corp/invitations/
Authorization: Bearer YOUR_ACCESS_TOKEN

Resend invitation email:

POST /api/cloud/organizations/acme-corp/invitations/{uuid}/resend/
Authorization: Bearer YOUR_ACCESS_TOKEN

Delete invitation:

DELETE /api/cloud/organizations/acme-corp/invitations/{uuid}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Note: Invitations use UUID tokens for security. Once accepted, they cannot be reused.

Permissions

Organizations support the following permissions:

Permission	Description
view_organization	View organization details
change_organization	Update organization settings
delete_organization	Delete the organization
manage_organization	Full management access (members, sites, settings)
invite_members	Send invitations to new members

Best Practices

1. Unique Slugs: Use meaningful, unique slugs for easy identification
2. Active Management: Keep is_active status updated to control access
3. Permission Assignment: Grant minimum required permissions to members
4. Regular Audits: Review member list and permissions regularly
5. Soft Deletes: Consider deactivating organizations instead of deleting them

Use Cases

Multi-Company SaaS

Serve multiple companies, each with their own organization, isolated data, and team members.

Department Isolation

Create separate organizations for different departments within a company (e.g., Engineering, Marketing, Sales).

Client Management

Agencies can create organizations for each client, managing their sites and resources separately.

Partner Ecosystems

Enable partners to have their own organizations while maintaining platform-level control.

Related Features

• Invitations - Invite and onboard new members with pre-configured access
• Sites - Create isolated cloud environments within organizations
• User Management - Manage organization members
• Groups - Organize members into groups with shared permissions
• Permissions - Fine-grained access control system