AI Integration Guide

LLM-Optimized Integration Guide

This guide is specifically designed for AI coding assistants like Cursor, Claude Code, GitHub Copilot, and other LLM-powered tools. Copy or download this guide and provide it to your AI assistant for seamless 3PM Auth SSO integration.

Important for AI Assistants

This is 3PM Auth, a custom SSO Identity Provider. It is NOT Better Auth or NextAuth. The JWT secret is never shared with client applications—always verify tokens via the/api/verify-token endpoint.

Quick Start Checklist

Setup

Copy Client ID and Client Secret

Add allowed callback URLs

Set environment variables

Implementation

Create auth callback route (exchanges GUID for JWT)

Create auth middleware (checks session cookie)

Create login redirect handler

Create logout handler

Key Concepts

GUID Token

Short-lived token (60s TTL) returned after login. Exchange it server-side for a JWT.

Client Secret

Server-side only! Never expose in client-side code or mobile apps.

Token Verification

Always verify tokens via /api/verify-token API call.

Session Cookies

Use httpOnly, secure (production), sameSite: "lax" for all session cookies.

Environment Variables

.env.localenv

# 3PM Auth Configuration
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

API Quick Reference

GET/authorize

Initiate SSO login flow

{IDP_URL}/authorize?clientId={CLIENT_ID}&next={CALLBACK_URL}

POST/api/exchange-token

Exchange GUID for JWT token (server-side only)

// Request
{
  "guid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "clientId": "3pm_xxxxxxxxxxxxxxxx",
  "clientSecret": "3pm_secret_xxxxxxxxxxxxxxxxxxxxxxxx"
}

// Response (tenant field only for tenant-based apps)
{
  "data": {
    "jwt": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "tenant": { "id": "...", "name": "...", "slug": "...", "role": "admin" }
  },
  "error": null
}

POST/api/verify-token

Verify JWT token and get user data

// Request
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "clientId": "3pm_xxxxxxxxxxxxxxxx",
  "clientSecret": "3pm_secret_xxxxxxxxxxxxxxxxxxxxxxxx"
}

// Response (tenant field only for tenant-based apps)
{
  "data": {
    "valid": true,
    "user": { ... },
    "tenant": { "id": "...", "name": "...", "slug": "...", "role": "admin" },
    "issuedAt": 1704355200,
    "expiresAt": 1704441600
  },
  "error": null
}

Cookie Configuration

// Always use these settings for session cookies
{
  httpOnly: true,           // Prevents JavaScript access
  secure: true,             // HTTPS only (in production)
  sameSite: "lax",          // CSRF protection
  path: "/",                // Available to all routes
  maxAge: 60 * 60 * 24      // 24 hours (or match IdP session)
}

Framework Integration

For complete integration examples, download the full AI Integration Guide which includes step-by-step instructions for:

Next.js

App Router with Server Components

Express.js / MERN

Backend + React Frontend

Flutter

Mobile with Deep Links

Ready to Integrate?

Download the complete AI Integration Guide (1700+ lines) with full code examples for Next.js, Express.js, React, and Flutter.

Last updated: January 2026

SSO Documentation →Data API Docs