Integration Guide

# 3PM Auth Configuration (Client App)
IDP_URL=https://idp.3pm.app
CLIENT_ID=3pm_xxxxxxxxxxxxxxxx
CLIENT_SECRET=3pm_secret_xxxxxxxxxxxxxxxxxxxxxxxx

# Your app's public URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Generate JWT secret (64+ characters)
openssl rand -base64 64

# Generate admin setup secret
openssl rand -hex 32

{
  "data": {
    "session": {
      "userId": "507f1f77bcf86cd799439011",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "profilePicUrl": "https://example.com/avatar.jpg"
    }
  },
  "error": null
}

{
  "data": {
    "requiresProfile": true,
    "registrationToken": "eyJhbGciOiJIUzI1NiIs...",
    "identifier": "newuser@example.com",
    "type": "email"
  },
  "error": null
}

// After successful token exchange
const { jwt, user } = await auth.exchangeToken(guid);

// Check if profile is incomplete (new OTP user)
if (!user.firstName || user.firstName.trim() === "") {
  // New user - redirect to onboarding
  navigate("/onboarding", { 
    state: { user, originalDestination: returnUrl } 
  });
} else {
  // Existing user - normal flow
  navigate(returnUrl);
}

{
  "userId": "507f1f77bcf86cd799439011",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tenantId": "60d5ecf4f1b5a23456789012",
  "tenantRole": "admin",
  "iat": 1699999999,
  "exp": 1700086399,
  "iss": "3pm-auth-idp"
}

function TenantSwitcher() {
  const [tenants, setTenants] = useState([]);
  const [activeTenantId, setActiveTenantId] = useState("");

  useEffect(() => {
    fetch("/api/tenant/list", { credentials: "include" })
      .then(res => res.json())
      .then(data => {
        setTenants(data.data?.tenants || []);
        setActiveTenantId(data.data?.activeTenantId || "");
      });
  }, []);

  const switchTenant = async (tenantId) => {
    await fetch("/api/tenant/switch", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      credentials: "include",
      body: JSON.stringify({ tenantId }),
    });
    window.location.reload();
  };

  return (
    <select value={activeTenantId} onChange={(e) => switchTenant(e.target.value)}>
      {tenants.map((t) => (
        <option key={t.id} value={t.id}>{t.name} ({t.role})</option>
      ))}
    </select>
  );
}

const axios = require("axios");

const { IDP_URL, CLIENT_ID, CLIENT_SECRET } = process.env;

async function verifyToken(token) {
  try {
    const response = await axios.post(`${IDP_URL}/api/verify-token`, {
      token,
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
    });

    const { data, error } = response.data;

    if (error || !data?.valid) {
      return null;
    }

    return data.user;
  } catch (error) {
    console.error("Token verification failed:", error.message);
    return null;
  }
}

// Express middleware
async function requireAuth(req, res, next) {
  const token = req.cookies.session;

  if (!token) {
    return res.status(401).json({ error: "Authentication required" });
  }

  const user = await verifyToken(token);

  if (!user) {
    return res.status(401).json({ error: "Invalid or expired session" });
  }

  req.user = user;
  next();
}

module.exports = { verifyToken, requireAuth };

const IDP_URL = process.env.IDP_URL!;
const CLIENT_ID = process.env.CLIENT_ID!;
const CLIENT_SECRET = process.env.CLIENT_SECRET!;

export interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  profilePicUrl?: string;
}

export async function verifyToken(token: string): Promise<User | null> {
  try {
    const response = await fetch(`${IDP_URL}/api/verify-token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        token,
        clientId: CLIENT_ID,
        clientSecret: CLIENT_SECRET,
      }),
    });

    const result = await response.json();

    if (result.error || !result.data?.valid) {
      return null;
    }

    return result.data.user;
  } catch {
    return null;
  }
}

import os
import requests

IDP_URL = os.environ['IDP_URL']
CLIENT_ID = os.environ['CLIENT_ID']
CLIENT_SECRET = os.environ['CLIENT_SECRET']

def verify_token(token: str) -> dict | None:
    try:
        response = requests.post(
            f'{IDP_URL}/api/verify-token',
            json={
                'token': token,
                'clientId': CLIENT_ID,
                'clientSecret': CLIENT_SECRET,
            }
        )
        result = response.json()
        
        if result.get('error') or not result.get('data', {}).get('valid'):
            return None
            
        return result['data']['user']
    except Exception as e:
        print(f'Token verification failed: {e}')
        return None

{
  "userId": "507f1f77bcf86cd799439011",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "profilePicUrl": "https://example.com/avatar.jpg",
  "iat": 1699999999,
  "exp": 1700086399,
  "iss": "3pm-auth-idp"
}

{
  "userId": "507f1f77bcf86cd799439011",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tenantId": "60d5ecf4f1b5a23456789012",
  "tenantRole": "admin",
  "iat": 1699999999,
  "exp": 1700086399,
  "iss": "3pm-auth-idp"
}

async function requireTenantAuth(req, res, next) {
  const token = req.cookies.session;
  
  if (!token) {
    return res.status(401).json({ error: "Authentication required" });
  }

  // Verify token via 3PM Auth API
  const response = await axios.post(`${IDP_URL}/api/verify-token`, {
    token,
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
  });

  const { data, error } = response.data;

  if (error || !data?.valid) {
    return res.status(401).json({ error: "Invalid session" });
  }

  // Check tenant membership for tenant-based apps
  if (!data.user.tenantId) {
    return res.status(403).json({ error: "Tenant membership required" });
  }

  req.user = data.user;
  req.tenantId = data.user.tenantId;
  req.tenantRole = data.user.tenantRole;
  next();
}

// Check minimum role
function requireMinRole(minRole) {
  const roleHierarchy = { member: 0, admin: 1, owner: 2 };

  return (req, res, next) => {
    if (roleHierarchy[req.tenantRole] < roleHierarchy[minRole]) {
      return res.status(403).json({ error: "Insufficient permissions" });
    }
    next();
  };
}

// Usage
app.post("/api/tenant/invite", 
  requireTenantAuth, 
  requireMinRole("admin"), 
  handleInvite
);

app.put("/api/tenant/settings", 
  requireTenantAuth, 
  requireMinRole("owner"), 
  handleSettings
);

async function handleAuth(guid) {
  try {
    const result = await auth.exchangeToken(guid);
    return result;
  } catch (error) {
    if (error.message.includes("expired")) {
      // Token expired, redirect to login
      window.location.href = "/login?error=session_expired";
    } else if (error.message.includes("credentials")) {
      // Configuration error
      console.error("Auth configuration error");
    } else {
      // Generic error
      console.error("Auth error:", error);
    }
    throw error;
  }
}