API for Third-Party Service Integrations with SaaS Application

SaaS Integrations with Third-Party APIs

Integrations extend product capabilities without building from scratch: Slack notifications, GitHub synchronization, Jira tasks, Salesforce contacts. Key questions—token storage, rate limit handling, and webhook security.

Storing OAuth tokens for integrations

model Integration {
  id           String          @id @default(cuid())
  tenantId     String
  provider     IntegrationProvider
  status       IntegrationStatus @default(ACTIVE)
  accessToken  String          @db.Text  // encrypted
  refreshToken String?         @db.Text  // encrypted
  tokenExpiresAt DateTime?
  scope        String?
  externalId   String?         // provider account ID
  metadata     Json?           // workspaceId, teamId, etc.
  createdAt    DateTime        @default(now())

  tenant Tenant @relation(fields: [tenantId], references: [id])

  @@unique([tenantId, provider])
}

enum IntegrationProvider {
  SLACK
  GITHUB
  JIRA
  SALESFORCE
  HUBSPOT
  GOOGLE_SHEETS
}

// Token encryption before saving
import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';

const ENCRYPTION_KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY!, 'hex');

export function encryptToken(token: string): string {
  const iv = randomBytes(16);
  const cipher = createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);

  const encrypted = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]);
  const authTag = cipher.getAuthTag();

  return [iv.toString('hex'), authTag.toString('hex'), encrypted.toString('hex')].join(':');
}

export function decryptToken(encryptedToken: string): string {
  const [ivHex, authTagHex, encryptedHex] = encryptedToken.split(':');

  const decipher = createDecipheriv(
    'aes-256-gcm',
    ENCRYPTION_KEY,
    Buffer.from(ivHex, 'hex')
  );

  decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));
  return decipher.update(Buffer.from(encryptedHex, 'hex')) + decipher.final('utf8');
}

Slack: sending notifications

// lib/integrations/slack.ts
import { WebClient } from '@slack/web-api';

export async function sendSlackNotification(
  tenantId: string,
  message: SlackMessage
): Promise<void> {
  const integration = await db.integration.findUnique({
    where: { tenantId_provider: { tenantId, provider: 'SLACK' } }
  });

  if (!integration || integration.status !== 'ACTIVE') return;

  const token = decryptToken(integration.accessToken);
  const client = new WebClient(token);

  const channel = (integration.metadata as { channelId?: string })?.channelId;

  await client.chat.postMessage({
    channel: channel ?? '#general',
    text: message.text,
    blocks: message.blocks,
    unfurl_links: false,
  });
}

// Slack OAuth installation
export async function installSlackApp(
  tenantId: string,
  code: string
): Promise<void> {
  const response = await fetch('https://slack.com/api/oauth.v2.access', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      code,
      client_id: process.env.SLACK_CLIENT_ID!,
      client_secret: process.env.SLACK_CLIENT_SECRET!,
      redirect_uri: `${process.env.APP_URL}/integrations/slack/callback`,
    }),
  });

  const data = await response.json();
  if (!data.ok) throw new Error(data.error);

  await db.integration.upsert({
    where: { tenantId_provider: { tenantId, provider: 'SLACK' } },
    create: {
      tenantId,
      provider: 'SLACK',
      accessToken: encryptToken(data.access_token),
      externalId: data.team.id,
      metadata: {
        teamName: data.team.name,
        channelId: data.incoming_webhook?.channel_id,
        channelName: data.incoming_webhook?.channel,
      },
    },
    update: {
      accessToken: encryptToken(data.access_token),
      status: 'ACTIVE',
    }
  });
}

GitHub: repository synchronization

// lib/integrations/github.ts
import { Octokit } from '@octokit/rest';

export async function createGithubClient(tenantId: string): Promise<Octokit> {
  const integration = await db.integration.findUniqueOrThrow({
    where: { tenantId_provider: { tenantId, provider: 'GITHUB' } }
  });

  const token = decryptToken(integration.accessToken);

  // Check token expiry (GitHub App tokens)
  if (integration.tokenExpiresAt && integration.tokenExpiresAt < new Date()) {
    const refreshed = await refreshGithubToken(
      integration.id,
      decryptToken(integration.refreshToken!)
    );
    return new Octokit({ auth: refreshed });
  }

  return new Octokit({ auth: token });
}

// Rate limiting: GitHub allows 5000 req/hour
export async function githubWithRateLimit<T>(
  client: Octokit,
  fn: (client: Octokit) => Promise<T>
): Promise<T> {
  const rateLimit = await client.rateLimit.get();
  const remaining = rateLimit.data.rate.remaining;

  if (remaining < 100) {
    const resetAt = new Date(rateLimit.data.rate.reset * 1000);
    const waitMs = resetAt.getTime() - Date.now();
    console.warn(`GitHub rate limit low (${remaining}), waiting ${waitMs}ms`);
    await new Promise(resolve => setTimeout(resolve, waitMs));
  }

  return fn(client);
}

Webhooks from third-party services

// app/api/webhooks/github/route.ts
import { Webhooks } from '@octokit/webhooks';

const webhooks = new Webhooks({
  secret: process.env.GITHUB_WEBHOOK_SECRET!,
});

export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get('x-hub-signature-256')!;

  // Signature verification
  const isValid = await webhooks.verify(body, signature);
  if (!isValid) {
    return new Response('Invalid signature', { status: 401 });
  }

  const event = JSON.parse(body);
  const eventType = request.headers.get('x-github-event');

  // Handle event
  if (eventType === 'push') {
    const installationId = event.installation?.id;
    // Find tenant by GitHub installation ID
    const integration = await db.integration.findFirst({
      where: {
        provider: 'GITHUB',
        externalId: installationId?.toString(),
      }
    });

    if (integration) {
      await processGithubPush(integration.tenantId, event);
    }
  }

  return Response.json({ received: true });
}

Developing an integration system (Slack + GitHub + 2 providers) with token encryption — 5–8 working days.