Multi-Tenant Social Media API Architecture: Build Your SaaS Backend the Right Way

Organization (your account)
├── API Keys (up to 50, org-scoped)
├── Webhooks (up to 5, org-scoped)
├── Subscription (FREE / PRO / BUSINESS)
│
├── Team "Client A"
│   ├── Social Accounts (Instagram, TikTok, LinkedIn...)
│   ├── Posts
│   └── Uploads
│
├── Team "Client B"
│   ├── Social Accounts (Twitter, Facebook...)
│   ├── Posts
│   └── Uploads
│
└── Team "Client C"
    └── ...

-- Your users table (you already have this)
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  name TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Map your users to bundle.social teams
CREATE TABLE workspaces (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  name TEXT NOT NULL,
  bundle_team_id TEXT NOT NULL,  -- bundle.social team ID
  created_at TIMESTAMP DEFAULT NOW()
);

import { BundleSocial } from 'bundlesocial';

const bundle = new BundleSocial(process.env.BUNDLE_API_KEY);

async function createWorkspace(userId: string, workspaceName: string) {
  // 1. Create team in bundle.social
  const team = await bundle.team.teamCreate({
    requestBody: { name: workspaceName }
  });

  // 2. Store the mapping in YOUR database
  await db.query(
    'INSERT INTO workspaces (id, user_id, name, bundle_team_id) VALUES ($1, $2, $3, $4)',
    [generateUUID(), userId, workspaceName, team.id]
  );

  return { workspaceId: team.id, name: workspaceName };
}

// Every request is automatically scoped to your org
const response = await fetch('https://api.bundle.social/api/v1/team', {
  headers: {
    'x-api-key': process.env.BUNDLE_API_KEY,
    'Content-Type': 'application/json',
  }
});
// Returns only YOUR teams, not anyone else's

async function onUserSignup(user: { id: string; name: string }) {
  const team = await bundle.team.teamCreate({
    requestBody: { name: `${user.name}'s Workspace` }
  });

  // Store team ID in your database
  await db.workspaces.create({
    userId: user.id,
    bundleTeamId: team.id,
    name: team.name,
  });

  return team;
}

const response = await fetch(
  'https://api.bundle.social/api/v1/social-account/create-portal-link',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.BUNDLE_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      teamId: teamId,
      redirectUrl: 'https://yourapp.com/dashboard',
      socialAccountTypes: [
        'INSTAGRAM', 'TIKTOK', 'LINKEDIN',
        'FACEBOOK', 'YOUTUBE', 'TWITTER'
      ],
      // White label it
      logoUrl: 'https://yourapp.com/logo.png',
      hidePoweredBy: true,
    })
  }
);

const portal = await response.json();
// Redirect your user to portal.url

const upload = await bundle.upload.uploadCreate({
  formData: {
    teamId: teamId,
    file: new Blob([videoBuffer], { type: 'video/mp4' }),
  }
});
// upload.id → use this in the post

const post = await bundle.post.postCreate({
  requestBody: {
    teamId: teamId,
    title: 'Your post title',
    postDate: '2026-02-15T10:00:00Z',
    status: 'SCHEDULED',
    socialAccountTypes: ['INSTAGRAM', 'TIKTOK'],
    data: {
      INSTAGRAM: {
        type: 'POST',
        text: 'Your content here #hashtag',
        uploadIds: [upload.id],
      },
      TIKTOK: {
        text: 'Your content here',
        uploadIds: [upload.id],
        privacy: 'PUBLIC_TO_EVERYONE',
      },
    },
  }
});

import express from 'express';
import { BundleSocial } from 'bundlesocial';

const bundle = new BundleSocial(process.env.BUNDLE_API_KEY);
const app = express();

app.post(
  '/webhooks/bundle',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-signature'] as string;

    // Verify the signature - ALWAYS do this
    const event = bundle.webhooks.constructEvent(
      req.body,
      signature,
      process.env.BUNDLE_WEBHOOK_SECRET
    );

    switch (event.type) {
      case 'post.published':
        await db.posts.update({
          where: { bundlePostId: event.data.id },
          data: {
            status: 'published',
            publishedAt: event.data.postedDate,
          }
        });
        await notifyUser(event.data.teamId, 'Your post is live!');
        break;

      case 'post.failed':
        await db.posts.update({
          where: { bundlePostId: event.data.id },
          data: { status: 'failed' }
        });
        await notifyUser(event.data.teamId, 'Post failed - check the details');
        break;

      case 'social-account.created':
        await syncSocialAccounts(event.data.teamId);
        break;

      case 'social-account.deleted':
        await removeSocialAccount(event.data.teamId, event.data.id);
        break;
    }

    res.status(200).send('ok');
  }
);

async function canUserPost(workspaceId: string): Promise<boolean> {
  // Check YOUR limits first
  const usage = await db.query(
    'SELECT COUNT(*) FROM posts WHERE workspace_id = $1 AND created_at > NOW() - INTERVAL \'30 days\'',
    [workspaceId]
  );

  const plan = await getUserPlan(workspaceId);
  if (usage.count >= plan.monthlyPostLimit) {
    throw new Error('Monthly post limit reached. Upgrade your plan.');
  }

  // If your check passes, the API will enforce its own limits
  // Handle 400/429 responses gracefully
  return true;
}

User clicks "Connect Instagram" in YOUR app
  → Redirect to portal URL (with your logo, no bundle.social branding)
    → User completes OAuth on Instagram
      → Redirect back to YOUR app
        → Webhook fires: social-account.created