.do
Business

organizations

Multi-tenant organization management

organizations

Multi-tenant organizations with hierarchies, team management, billing, access control, branding, and resource isolation for enterprise deployments.

Overview

The organizations primitive provides comprehensive multi-tenant organization management including organization hierarchies, team structures, billing, access control, resource quotas, and customization.

SDK Object Mapping

This primitive maps to the user SDK object (one of 8 core) for authentication and authorization:

import { user, organizations, on, send } from 'sdk.do'

// USER - Check organization membership (user is one of 8 core SDK objects)
const orgs = await user.organizations()
const isAdmin = await user.hasRole('org-123', 'admin')
const permissions = await user.permissions('org-123')

// Create organization
const org = await organizations.create({
  name: 'Acme Corporation',
  slug: 'acme',
  owner: user.id,
})

// Organization events via ON (on is one of 8 core SDK objects)
on($.Organization.created, async ({ organization }) => {
  // Setup default team
  await send($.Team.create, {
    organizationId: organization.id,
    name: 'Default Team',
    members: [organization.owner],
  })
})

// Organization-scoped operations
await user.switchOrganization('org-123')
const currentOrg = await user.currentOrganization()

Subdomain Architecture

The organizations primitive uses infinite free subdomains for customer organizations:

organizations.do                   # Root - Organization management
├── {slug}.organizations.do        # Customer organization workspace
└── {custom}.organizations.do      # Custom organization domains

Each organization gets a free subdomain (e.g., acme.organizations.do) for their workspace, enabling multi-tenant isolation without purchasing domains.

Quick Example

import { organizations } from 'sdk.do'

// Create organization
const org = await organizations.create({
  name: 'Acme Corporation',
  slug: 'acme',
  type: 'enterprise',
  metadata: {
    industry: 'Technology',
    size: '100-500',
    country: 'US',
  },
})

console.log(`Organization ID: ${org.id}`)
console.log(`Slug: ${org.slug}`)

// Get organization
const retrieved = await organizations.get(org.id)
console.log(`Name: ${retrieved.name}`)
console.log(`Members: ${retrieved.memberCount}`)

// Update organization
await organizations.update(org.id, {
  name: 'Acme Corporation Inc.',
  website: 'https://acme.com',
  logo: 'https://cdn.acme.com/logo.png',
})

// Organization settings
await organizations.setSettings(org.id, {
  defaultTimezone: 'America/New_York',
  allowedDomains: ['acme.com', 'acmecorp.com'],
  requireMFA: true,
  sessionTimeout: { hours: 8 },
  ipWhitelist: ['192.168.1.0/24'],
})

// Add member
await organizations.addMember(org.id, {
  userId: 'user-123',
  role: 'admin',
  permissions: ['manage_users', 'manage_billing'],
})

// List members
const members = await organizations.listMembers(org.id)

members.forEach((member) => {
  console.log(`${member.user.name}: ${member.role}`)
  console.log(`  Permissions: ${member.permissions.join(', ')}`)
})

// Remove member
await organizations.removeMember(org.id, 'user-123')

// Update member role
await organizations.updateMember(org.id, 'user-456', {
  role: 'member',
  permissions: ['read_projects'],
})

// Create team
const team = await organizations.createTeam(org.id, {
  name: 'Engineering',
  description: 'Engineering team',
  members: ['user-123', 'user-456', 'user-789'],
})

// Organization hierarchy
const parent = await organizations.create({
  name: 'Acme Holdings',
  type: 'enterprise',
})

await organizations.setParent(org.id, parent.id)

// List child organizations
const children = await organizations.listChildren(parent.id)

children.forEach((child) => {
  console.log(`${child.name}: ${child.memberCount} members`)
})

// Billing
await organizations.setBilling(org.id, {
  plan: 'enterprise',
  billingEmail: '[email protected]',
  paymentMethod: 'card',
  billingCycle: 'annual',
})

const billing = await organizations.getBilling(org.id)
console.log(`Plan: ${billing.plan}`)
console.log(`Next billing date: ${billing.nextBillingDate}`)
console.log(`Amount: $${billing.amount}`)

// Usage and quotas
await organizations.setQuotas(org.id, {
  users: 1000,
  projects: 100,
  storage: 1099511627776, // 1TB
  apiRequests: { perMonth: 10000000 },
})

const usage = await organizations.getUsage(org.id)
console.log(`Users: ${usage.users}/${usage.quotas.users}`)
console.log(`Projects: ${usage.projects}/${usage.quotas.projects}`)
console.log(`Storage: ${usage.storage}/${usage.quotas.storage}`)

// Branding
await organizations.setBranding(org.id, {
  logo: 'https://cdn.acme.com/logo.png',
  colors: {
    primary: '#FF6B6B',
    secondary: '#4ECDC4',
  },
  customDomain: 'app.acme.com',
})

// Invitations
const invitation = await organizations.invite(org.id, {
  email: '[email protected]',
  role: 'member',
  expiresIn: { days: 7 },
})

console.log(`Invitation URL: ${invitation.url}`)

// Accept invitation
await organizations.acceptInvitation(invitation.token, {
  userId: 'user-999',
})

// Resource isolation
await organizations.createNamespace(org.id, {
  name: 'production',
  isolation: 'strict',
  resources: {
    cpu: '4 cores',
    memory: '16GB',
    storage: '100GB',
  },
})

// Audit log
const auditLog = await organizations.getAuditLog(org.id, {
  timeRange: { last: '30d' },
  actions: ['member_added', 'member_removed', 'settings_updated'],
})

auditLog.forEach((entry) => {
  console.log(`${entry.timestamp}: ${entry.action}`)
  console.log(`  Actor: ${entry.actor}`)
  console.log(`  Target: ${entry.target}`)
})

// Organization roles
await organizations.defineRole(org.id, {
  name: 'Project Manager',
  permissions: ['read_projects', 'create_projects', 'update_projects', 'manage_team_members'],
})

// SSO configuration
await organizations.configureSSOO(org.id, {
  provider: 'okta',
  domain: 'acme.okta.com',
  clientId: 'client-123',
  clientSecret: 'secret-456',
  autoProvision: true,
})

// Data residency
await organizations.setDataResidency(org.id, {
  region: 'us-east-1',
  enforcement: 'strict',
  allowedRegions: ['us-east-1', 'us-west-2'],
})

// Organization transfer
await organizations.transfer(org.id, {
  newOwner: 'user-999',
  transferBilling: true,
})

// Delete organization
await organizations.delete(org.id, {
  deleteData: true,
  confirmationToken: 'confirm-delete-123',
})

// Search organizations
const results = await organizations.search({
  query: 'acme',
  type: 'enterprise',
  country: 'US',
})

// Organization statistics
const stats = await organizations.getStats(org.id, {
  timeRange: { last: '30d' },
})

console.log(`Active users: ${stats.activeUsers}`)
console.log(`New projects: ${stats.newProjects}`)
console.log(`API usage: ${stats.apiRequests}`)

// Webhooks for organization events
on(organizations.memberAdded, async (org, member) => {
  console.log(`New member added to ${org.name}: ${member.user.email}`)
  await sendWelcomeEmail(member.user.email)
})

on(organizations.billingUpdated, async (org, billing) => {
  console.log(`Billing updated for ${org.name}`)
  await notifyFinance(org, billing)
})

// Export organization data
await organizations.export(org.id, {
  format: 'json',
  include: ['members', 'teams', 'projects', 'settings'],
})

Core Capabilities

  • Multi-Tenancy - Isolated organization environments
  • Hierarchies - Parent-child organization structures
  • Team Management - Teams and member roles
  • Billing - Per-organization billing
  • Access Control - Role-based permissions

Access Methods

SDK

TypeScript/JavaScript library for organizations

await organizations.create({ name: 'Acme Corporation', slug: 'acme' })

SDK Documentation

CLI

Command-line tool for organization operations

do org create "Acme Corporation" --slug acme

CLI Documentation

API

REST/RPC endpoints for organization management

curl -X POST https://api.do/v1/organizations -d '{"name":"Acme Corporation"}'

API Documentation

MCP

Model Context Protocol for AI-driven organizations

Create a new organization named Acme Corporation with slug acme

MCP Documentation

Child Primitives

  • teams - Team collaboration within organizations

Child Primitives

  • teams - Team collaboration within organizations
  • user - User authentication and authorization (SDK object mapping)
  • users - User management
  • billing - Organization billing management
  • on - Organization event handlers