Overview

TendSocial v3.0 introduces native OAuth integration with 12 social media platforms. This guide covers the complete setup and integration process for the platform connections feature.

Table of Contents

• Prerequisites
• Backend Setup
• Frontend Setup
• Platform-Specific Configuration
• Testing
• Troubleshooting

Prerequisites

Before integrating platform connections, ensure you have:

• ✅ Phase 1 backend implementation complete (all 12 platform adapters)
• ✅ Database schema with SocialAccount model
• ✅ Encryption key configured
• ✅ OAuth routes registered

See also:

• OAuth Setup Guide

Backend Setup

1. Register OAuth Routes

In apps/backend/src/app.ts, add the platform initialization and routes:

import { initializePlatformAdapters } from './adapters/platforms/index.js';
import socialAccountsRoutes from './routes/social/accounts.js';

export async function buildApp() {
    const app = Fastify({ /* your config */ });
    
    // Initialize platform adapters on startup
    initializePlatformAdapters();
    
    // ... your existing middleware and routes
    
    // Register social accounts routes
    await app.register(socialAccountsRoutes);
    
    return app;
}

2. Environment Variables

Configure all required OAuth credentials in .env:

# Encryption (REQUIRED)
ENCRYPTION_KEY=  # Generate: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# OAuth Callbacks
OAUTH_REDIRECT_BASE_URL=http://localhost:5000
FRONTEND_URL=http://localhost:3000

# Facebook/Instagram/Threads
FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret

# LinkedIn
LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secret

# Twitter/X
TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret

# Google (YouTube, Google Business)
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

# TikTok
TIKTOK_CLIENT_KEY=your_client_key
TIKTOK_CLIENT_SECRET=your_client_secret

# Pinterest
PINTEREST_APP_ID=your_app_id
PINTEREST_APP_SECRET=your_app_secret

# Reddit
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret

# Mastodon (optional, per-instance)
MASTODON_CLIENT_ID=your_client_id
MASTODON_CLIENT_SECRET=your_client_secret

See Environment Variables Guide for complete documentation.

3. Generate Prisma Client

If you haven't already:

cd apps/backend
pnpm prisma generate

4. Start Backend

cd apps/backend
pnpm dev

Verify the platform adapters are initialized by checking the console output for:

🔌 Initializing platform adapters...
✅ Platform adapters initialized
   → 12 platforms registered

Frontend Setup

1. Install Dependencies

cd apps/marketing
pnpm add react-router-dom

2. Configure Environment

Create .env in apps/marketing/:

VITE_API_URL=http://localhost:5000

3. Add Routes

Update apps/marketing/src/App.tsx to include the platform connection routes:

import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { PlatformConnections } from './components/PlatformConnections';
import { OAuthCallback } from './components/OAuthCallback';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/connections" element={<PlatformConnections />} />
        <Route path="/oauth/callback/:platform" element={<OAuthCallback />} />
        {/* Your other routes */}
      </Routes>
    </BrowserRouter>
  );
}

export default App;

4. Component Files

The following components are already created in apps/marketing/src/components/:

• PlatformConnections.tsx - Main connection management UI
• OAuthCallback.tsx - OAuth redirect handler

5. Start Frontend

cd apps/marketing
pnpm dev

Navigate to http://localhost:5173/connections to access the platform connections interface.

Platform-Specific Configuration

Each platform requires developer account setup and OAuth app creation. See the OAuth Setup Guide for detailed instructions for each platform.

Quick Links by Platform

Platform	Developer Portal	Callback URL Format
Facebook	developers.facebook.com	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/facebook_page
Instagram	Uses Facebook OAuth	Same as Facebook
LinkedIn	linkedin.com/developers	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/linkedin_page
Twitter/X	developer.twitter.com	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/twitter
YouTube	console.cloud.google.com	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/youtube
TikTok	developers.tiktok.com	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/tiktok_business
Pinterest	developers.pinterest.com	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/pinterest
Google Business	Same as YouTube	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/google_business
Threads	Uses Facebook OAuth	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/threads
Reddit	reddit.com/prefs/apps	{OAUTH_REDIRECT_BASE_URL}/api/social/accounts/callback/reddit

Note: Bluesky and Mastodon use alternative authentication methods (app passwords and per-instance OAuth respectively). See the OAuth Setup Guide for details.

Testing

Manual Testing Checklist

1. Backend Health Check

   curl http://localhost:5000/api/social/accounts \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

   Expected: {"accounts": []}

2. Initiate OAuth Flow

   • Navigate to /connections
   • Click "Connect" on a platform
   • Verify redirect to platform OAuth page

3. Complete OAuth

   • Authorize app on platform
   • Verify redirect to /oauth/callback/:platform
   • Check for success message
   • Verify redirect to /connections

4. View Connected Account

   • Verify account appears in "Connected Accounts"
   • Check status shows "Connected"
   • Verify capabilities are displayed

5. Test Reconnect

   • For platforms with expiring tokens, test reconnect flow
   • Verify token refresh works

6. Test Disconnect

   • Click "Disconnect" on an account
   • Confirm dialog
   • Verify account is removed

Integration Testing

See Testing Conventions for testing guidelines.

Troubleshooting

Common Issues

"Encryption key not configured"

Solution: Generate and set ENCRYPTION_KEY in .env:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

"Platform not supported"

Solution: Ensure initializePlatformAdapters() is called before routes are registered in app.ts.

"OAuth state invalid"

Causes:

• ENCRYPTION_KEY mismatch between requests
• OAuth flow took longer than 10 minutes (state expired)
• State parameter was modified

Solution: Verify ENCRYPTION_KEY is consistent and retry the connection.

"Cannot find module '@atproto/api'"

Solution: Install Bluesky dependency:

cd apps/backend && pnpm install

Prisma Type Errors

Solution: Generate Prisma client:

cd apps/backend && pnpm prisma generate

Platform-Specific Issues

For platform-specific errors, see:

• Troubleshooting Guide
• OAuth Setup Guide

Architecture

For technical implementation details, see:

• Environment Variables
• Database Schema
• API Reference

Security

Platform connections implement multiple security layers:

• Token Encryption: All OAuth tokens encrypted at rest with AES-256-GCM
• CSRF Protection: OAuth state parameters encrypted and validated
• PKCE: Proof Key for Code Exchange for supported platforms (Twitter)
• Multi-Tenancy: Strict data isolation at database level

See Security Standards for more details.

Next Steps

After completing platform connections:

1. Test Publishing: Use connected accounts to publish content
2. Configure Webhooks: Set up real-time sync for comments/messages (Phase 3)
3. Enable Analytics: Configure analytics aggregation (Phase 8)
4. Team Channels: Add Slack, Discord, Teams connections (future)

Support

For additional help:

• OAuth Setup Guide
• Client Overview
• Contributing Guide