MindTickle Reference Architecture

Overview

Design a multi-tenant integration layer for the MindTickle sales enablement platform. Strict tenant data isolation is the primary driver, enforced at the database, cache, and queue levels so training data, quiz scores, and readiness analytics never cross organizational boundaries.

Instructions

1. Provision the prerequisites below with Row-Level Security enabled in PostgreSQL.
2. Configure SCIM 2.0 webhook endpoints to receive HR system user events.
3. Deploy the enablement service with tenant-scoped database connections.
4. Start the SCIM consumer and analytics aggregator as separate worker processes.
5. Validate tenant isolation by running cross-tenant query tests against RLS policies.

Prerequisites

• Node.js 18+, TypeScript 5, PostgreSQL 15 with RLS, Redis 7, RabbitMQ or SQS
• MindTickle API key with users:read, courses:read, analytics:read scopes
• SCIM 2.0 endpoint credentials for user provisioning

Architecture Diagram

HR System --> SCIM Webhook Ingester --> User Sync Service --> MindTickle API
                                             |
Client --> API Gateway --> EnablementService --+--> Analytics Aggregator
                                |
                         Tenant-scoped PostgreSQL (RLS)

Service Layer

class EnablementService {
  constructor(
    private api: MindTickleApiClient,
    private db: TenantScopedStore,
    private events: EventPublisher
  ) {}

  async syncCourseProgress(tenantId: string, userId: string): Promise<Progress> {
    const courses = await this.api.getUserCourses(userId);
    const progress = courses.map(c => ({
      courseId: c.id, status: c.status, score: c.quizScore, completedAt: c.completedAt,
    }));
    await this.db.upsertProgress(tenantId, userId, progress);
    await this.events.publish('progress.synced', { tenantId, userId });
    return { userId, courses: progress };
  }

  async processQuizResult(tenantId: string, result: QuizSubmission): Promise<void> {
    await this.db.recordQuizResult(tenantId, result);
    await this.events.publish('quiz.completed', { tenantId, ...result });
  }
}

Caching Strategy

class TenantCache {
  constructor(private redis: RedisClient) {}

  private key(tenantId: string, resource: string): string {
    return `tenant:${tenantId}:${resource}`;
  }

  async getUserRoster(tenantId: string): Promise<User[] | null> {
    const raw = await this.redis.get(this.key(tenantId, 'roster'));
    return raw ? JSON.parse(raw) : null;
  }

  async setUserRoster(tenantId: string, users: User[]): Promise<void> {
    await this.redis.setEx(this.key(tenantId, 'roster'), 600, JSON.st

MindTickle SDK Patterns

Overview

MindTickle's REST API serves sales enablement workflows including course management, quiz administration, user progress tracking, SCIM user provisioning, and coaching analytics. A structured SDK client is critical because MindTickle uses compound API keys with org-scoped tokens, returns progress data as nested completion trees with module-level granularity, and enforces strict SCIM schema compliance for user sync. These patterns provide org-aware authentication, typed models for training content hierarchies, progress query builders, and mock factories for sales readiness test scenarios.

Prerequisites

• Node.js 18+, TypeScript 5+
• MINDTICKLEAPIKEY environment variable (generated in Admin > Integrations > API Keys)
• MINDTICKLEORGID for multi-org deployments
• axios or node-fetch for HTTP transport

Singleton Client

interface MindTickleConfig {
  apiKey: string;
  orgId: string;
  baseUrl?: string;
  timeout?: number;
}

let client: MindTickleClient | null = null;

export function getMindTickleClient(overrides?: Partial<MindTickleConfig>): MindTickleClient {
  if (!client) {
    const config: MindTickleConfig = {
      apiKey: process.env.MINDTICKLE_API_KEY ?? '',
      orgId: process.env.MINDTICKLE_ORG_ID ?? '',
      baseUrl: 'https://api.mindtickle.com/v2',
      timeout: 15_000,
      ...overrides,
    };
    if (!config.apiKey || !config.orgId) throw new Error('MINDTICKLE_API_KEY and MINDTICKLE_ORG_ID are required');
    client = new MindTickleClient(config);
  }
  return client;
}

Error Wrapper

interface MindTickleError { statusCode: number; errorType: string; description: string; requestId: string; }

async function safeMindTickle<T>(fn: () => Promise<T>): Promise<T> {
  try { return await fn(); }
  catch (err: any) {
    const parsed: MindTickleError = {
      statusCode: err.response?.status ?? 500,
      errorType: err.response?.data?.error?.type ?? 'INTERNAL_ERROR',
      description: err.response?.data?.error?.description ?? err.message,
      requestId: err.response?.headers?.['x-request-id'] ?? 'unknown',
    };
    if (parsed.statusCode === 429) {
      const retryMs = parseInt(err.response?.headers?.['retry-after-ms'] ?? '3000', 10);
      await new Promise(r => setTimeout(r, retryMs));
      return fn();
    }
    if (parsed.errorType === 'SCIM_CONFLICT') throw new Error(`User already provisioned (req: ${parsed.requestId})`);
    if (parsed.statusCode === 403) throw new Error(`Org ${process.env.MINDTICKLE_ORG_ID} lacks permission: ${parsed.description}`);
    throw new Error(`MindTickle ${parsed.errorType} (${parsed.statusCode}): ${parsed.description}

MindTickle Security Basics

Overview

MindTickle integrations process employee PII through SCIM provisioning (names, emails, job titles, manager chains) and HR-sensitive data like course completion scores, certification status, and coaching assessments. The API uses bearer token authentication combined with a Company-Id header for multi-tenant isolation — omitting or spoofing this header can leak data across tenants. Webhook payloads carrying training completion events must be HMAC-verified to prevent injection of fraudulent compliance records.

Prerequisites

• Secrets manager (AWS SSM, GCP Secret Manager, or Vault) for API tokens
• HTTPS enforced on all SCIM and webhook endpoints
• Company-Id validated against an allowlist of known tenant identifiers
• .env files in .gitignore — never committed to version control
• Data retention policy for employee training records (GDPR/SOC2)

API Key Management

// MindTickle requires both bearer token and company ID for multi-tenant isolation
const MT_API_TOKEN = process.env.MINDTICKLE_API_KEY;
const MT_COMPANY_ID = process.env.MINDTICKLE_COMPANY_ID;

function validateMindTickleConfig(): void {
  if (!MT_API_TOKEN) throw new Error('Missing MINDTICKLE_API_KEY');
  if (!MT_COMPANY_ID) throw new Error('Missing MINDTICKLE_COMPANY_ID');
}

function mindtickleHeaders(): Record<string, string> {
  return {
    Authorization: `Bearer ${MT_API_TOKEN}`,
    'Company-Id': MT_COMPANY_ID!,
    'Content-Type': 'application/json',
  };
}
// Call validateMindTickleConfig() at startup — both values are required for every request

Webhook Signature Verification

import crypto from 'node:crypto';

const MT_WEBHOOK_SECRET = process.env.MINDTICKLE_WEBHOOK_SECRET!;

function verifyMindTickleWebhook(payload: string, signature: string, timestamp: string): boolean {
  // Reject stale webhooks (>5 min) to prevent replay attacks
  const age = Date.now() - parseInt(timestamp, 10) * 1000;
  if (age > 300_000) return false;

  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', MT_WEBHOOK_SECRET)
    .update(signedPayload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/mindtickle', (req, res) => {
  const sig = req.headers['x-mindtickle-signature'] as string;
  const ts = req.headers['x-mindtickle-timestamp'] as string;
  if (!sig || !ts || !verifyMindTickleWebhook(JSON.stringify(req.body), sig, ts)) {
    return res.status(401).json({ error: 'Invalid signature or stale timestamp' });
  }
  // Process verified training completion event
});

Input Vali

MindTickle Webhooks & Events

Overview

MindTickle emits webhook events as sales reps progress through enablement programs, complete courses, submit quizzes, and are provisioned or deprovisioned from the platform. These events enable integrations such as pushing completion certificates to an LMS, syncing learner progress to Salesforce rep profiles, triggering manager alerts when quiz scores fall below threshold, and automating user lifecycle management with your IdP. All payloads are HMAC-signed JSON scoped to your company, delivered over HTTPS.

Prerequisites

• MindTickle admin access with API & Webhooks permissions enabled
• Webhook endpoint URL accessible over HTTPS (TLS 1.2+)
• Company-scoped signing secret from MindTickle Admin > Integrations (MINDTICKLEWEBHOOKSECRET)
• Express.js with raw body parsing for HMAC verification

Webhook Registration

import axios from "axios";

const res = await axios.post(
  "https://api.mindtickle.com/v2/webhooks",
  {
    url: "https://your-app.com/webhooks/mindtickle",
    events: ["course.completed", "quiz.submitted", "user.provisioned",
             "user.deprovisioned", "module.progress"],
    companyId: process.env.MINDTICKLE_COMPANY_ID,
  },
  { headers: { Authorization: `Bearer ${process.env.MINDTICKLE_API_TOKEN}`,
               "Content-Type": "application/json" } }
);
console.log("Webhook ID:", res.data.webhookId);

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyMindTickleSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-mt-webhook-signature"] as string;
  const timestamp = req.headers["x-mt-webhook-timestamp"] as string;
  if (!signature || !timestamp) return res.status(401).send("Missing signature");

  const signedPayload = `${timestamp}:${(req as any).rawBody}`;
  const expected = crypto
    .createHmac("sha256", process.env.MINDTICKLE_WEBHOOK_SECRET!)
    .update(signedPayload)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(403).send("Invalid signature");
  }
  next();
}

Event Handler

app.post("/webhooks/mindtickle", verifyMindTickleSignature, (req, res) => {
  const { event, data, companyId } = req.body;

  switch (event) {
    case "course.completed":
      console.log(`${data.userId} completed "${data.courseName}" — score: ${data.score}%`);
      break;
    case "quiz.submitted":
      console.log(`Quiz "${data.quiz