JWT Tokens Guide

Learn how to implement server-side authentication using JWT tokens for secure backend-to-backend communication with Fanfare.

Overview

JWT (JSON Web Token) authentication allows your backend to securely authenticate consumers with Fanfare without client-side credential exposure. This is the recommended approach for production applications with existing user accounts. What you’ll learn:

Understanding Fanfare’s JWT authentication flow
Implementing server-side token exchange
Validating admission grants
Securing your integration

Complexity: Advanced Time to complete: 45 minutes

Prerequisites

Fanfare account with API credentials including secret key
Backend server (Node.js, Python, Go, etc.)
Basic understanding of JWT and authentication concepts

When to Use JWT Authentication

Use JWT authentication when:

Your application has existing user accounts
You need server-to-server authentication
You want to validate admission grants before checkout
You require enhanced security for high-value transactions

Authentication Architecture

Server-side authentication flow diagram showing browser SDK, backend exchange, Fanfare session, admission grant, and checkout validation.

Step 1: External Authentication Endpoint

Create a backend endpoint to generate exchange codes:

Node.js/Express

// routes/fanfare-auth.ts
import express from "express";

const router = express.Router();

const FANFARE_API_BASE_URL = "https://api.fanfare.io";
const FANFARE_ORG_ID = process.env.FANFARE_ORG_ID!;
const FANFARE_SECRET_KEY = process.env.FANFARE_SECRET_KEY!;

interface ExternalAuthPayload {
  provider: string;
  issuer: string;
  subject: string;
  claims?: Record<string, unknown>;
}

// POST /api/fanfare/authorize
router.post("/authorize", async (req, res) => {
  try {
    // 1. Verify the user is authenticated in YOUR system
    const user = req.user; // From your auth middleware
    if (!user) {
      return res.status(401).json({ error: "Unauthorized" });
    }

    // 2. Create external auth payload
    const payload: ExternalAuthPayload = {
      provider: "your-platform", // Unique identifier for your platform
      issuer: "https://your-domain.com", // Your domain
      subject: user.id, // User's unique ID in your system
      claims: {
        email: user.email,
        name: user.name,
        // Add any other relevant user data
        tier: user.subscriptionTier,
        createdAt: user.createdAt,
      },
    };

    // 3. Request exchange code from Fanfare
    const response = await fetch(`${FANFARE_API_BASE_URL}/auth/external/authorize`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Organization-Id": FANFARE_ORG_ID,
        "X-Secret-Key": FANFARE_SECRET_KEY, // Server-side only!
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      const error = await response.json();
      console.error("Fanfare auth error:", error);
      return res.status(500).json({ error: "Authentication failed" });
    }

    const { exchangeCode, expiresAt } = await response.json();

    // 4. Return exchange code to client
    // The code expires in 60 seconds
    res.json({ exchangeCode, expiresAt });
  } catch (error) {
    console.error("External auth error:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

export default router;

Python/FastAPI

# routes/fanfare_auth.py
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel
import httpx
import os

router = APIRouter()

FANFARE_API_BASE_URL = "https://api.fanfare.io"
FANFARE_ORG_ID = os.getenv("FANFARE_ORG_ID")
FANFARE_SECRET_KEY = os.getenv("FANFARE_SECRET_KEY")

class AuthResponse(BaseModel):
    exchangeCode: str
    expiresAt: str

@router.post("/authorize", response_model=AuthResponse)
async def authorize_fanfare(user: User = Depends(get_current_user)):
    """Generate Fanfare exchange code for authenticated user."""

    payload = {
        "provider": "your-platform",
        "issuer": "https://your-domain.com",
        "subject": str(user.id),
        "claims": {
            "email": user.email,
            "name": user.name,
        }
    }

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FANFARE_API_BASE_URL}/auth/external/authorize",
            json=payload,
            headers={
                "Content-Type": "application/json",
                "X-Organization-Id": FANFARE_ORG_ID,
                "X-Secret-Key": FANFARE_SECRET_KEY,
            }
        )

        if response.status_code != 200:
            raise HTTPException(status_code=500, detail="Fanfare auth failed")

        return response.json()

Step 2: Client-Side Exchange

Exchange the code in the browser:

import { useFanfare, useFanfareAuth } from "@fanfare-io/fanfare-sdk-react";
import { useEffect } from "react";

interface User {
  id: string;
  email: string;
}

function useFanfareExternalAuth(user: User | null) {
  const fanfare = useFanfare();
  const { isAuthenticated, session } = useFanfareAuth();

  useEffect(() => {
    async function authenticate() {
      if (!user || isAuthenticated) return;

      try {
        // 1. Get exchange code from your backend
        const response = await fetch("/api/fanfare/authorize", {
          method: "POST",
          credentials: "include", // Include auth cookies
        });

        if (!response.ok) {
          throw new Error("Failed to get exchange code");
        }

        const { exchangeCode } = await response.json();

        // 2. Exchange for Fanfare session
        await fanfare.auth.exchangeExternal({ exchangeCode });

        console.log("Fanfare authentication successful");
      } catch (error) {
        console.error("Fanfare auth failed:", error);
      }
    }

    authenticate();
  }, [user, isAuthenticated, fanfare]);

  return { isAuthenticated, session };
}

Step 3: Grant Validation Endpoint

Validate admission grants during checkout:

Node.js/Express

// routes/validate-admission.ts
import express from "express";

const router = express.Router();

interface ValidationRequest {
  admissionGrant: string;
}

// POST /api/validate-admission
router.post("/validate-admission", async (req, res) => {
  try {
    const { admissionGrant } = req.body as ValidationRequest;
    const isValid = await validateAdmissionGrant({ admissionGrant });

    if (!isValid) {
      return res.status(403).json({
        valid: false,
        error: "Invalid or expired admission grant",
      });
    }

    // Grant is valid - allow checkout to proceed
    res.json({ valid: true });
  } catch (error) {
    console.error("Validation error:", error);
    res.status(500).json({ error: "Validation failed" });
  }
});

export default router;

Step 4: Secure Checkout Flow

Validate admission before processing checkout:

// routes/checkout.ts
import express from "express";

const router = express.Router();

interface CheckoutRequest {
  admissionGrant: string;
  experienceId: string;
  cart: CartItem[];
}

router.post("/checkout", async (req, res) => {
  const { admissionGrant, cart } = req.body as CheckoutRequest;

  // 1. Validate admission grant with Fanfare
  const validationResult = await validateAdmissionGrant({ admissionGrant });

  if (!validationResult) {
    return res.status(403).json({
      error: "Invalid admission",
      message: "Your access has expired or is invalid",
      code: "ADMISSION_INVALID",
    });
  }

  // 2. Process the order
  try {
    const order = await processOrder({
      cart,
      admissionGrant,
    });

    // 3. Record the successful checkout against the admission
    await recordAdmissionCheckout({ admissionGrant, orderId: order.id });

    res.json({
      success: true,
      orderId: order.id,
    });
  } catch (error) {
    res.status(500).json({
      error: "Checkout failed",
      message: error instanceof Error ? error.message : "Unknown error",
    });
  }
});

export default router;

Step 5: JWT Token Structure

Understanding the tokens Fanfare uses:

Access Token Payload

interface AccessTokenPayload {
  consumerId: string;
  organizationId: string;
  sessionId: string;
  email?: string;
  phone?: string;
  isGuest?: boolean;
  iat: number; // Issued at
  exp: number; // Expiration
  iss: string; // Issuer: "consumer-app"
}

Admission Grant Context

interface AdmissionGrantContext {
  admissionGrant: string;
  expiresAt?: number;
}

Step 6: Security Best Practices

Protect Your Secret Key

// ❌ Don't do this
const response = await fetch("/api/fanfare", {
  headers: {
    "X-Secret-Key": "sk_live_xxx", // NEVER expose in client code
  },
});

// ✅ Do this - server-side only
// Your backend handles all secret key operations
const response = await fetch("/your-backend/api/fanfare/authorize");

Validate Token Origin

// Verify the admission originated from expected experience
async function validateAdmissionContext(token: string, expectedExperienceId: string) {
  const decoded = decodeAdmissionToken(token);

  if (decoded.experienceId !== expectedExperienceId) {
    throw new Error("Token does not match expected experience");
  }

  return decoded;
}

Implement Rate Limiting

import rateLimit from "express-rate-limit";

const authLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 10, // 10 requests per minute
  message: { error: "Too many auth requests" },
});

router.post("/authorize", authLimiter, async (req, res) => {
  // ... handler
});

Validate Claims

function validateExternalClaims(claims: Record<string, unknown>) {
  // Ensure claims don't exceed size limit
  const claimsJson = JSON.stringify(claims);
  if (claimsJson.length > 10000) {
    throw new Error("Claims too large");
  }

  // Sanitize sensitive data
  const sanitized = { ...claims };
  delete sanitized.password;
  delete sanitized.ssn;
  delete sanitized.creditCard;

  return sanitized;
}

Step 7: Error Handling

Handle common authentication errors:

async function handleFanfareAuth(user: User) {
  try {
    const { exchangeCode } = await fetch("/api/fanfare/authorize", {
      method: "POST",
      credentials: "include",
    }).then((r) => r.json());

    await fanfare.auth.exchangeExternal({ exchangeCode });
  } catch (error) {
    if (error instanceof Error) {
      switch (error.message) {
        case "exchange_code_expired":
          // Code expired (60 second TTL)
          // Retry with new code
          return handleFanfareAuth(user);

        case "invalid_exchange_code":
          // Code already used or invalid
          console.error("Invalid exchange code");
          break;

        case "consumer_conflict":
          // External identity already linked to different consumer
          showConflictResolution();
          break;

        default:
          console.error("Auth error:", error.message);
      }
    }
  }
}

Complete Integration Example

Backend (Node.js)

// app.ts
import express from "express";
import fanfareAuthRouter from "./routes/fanfare-auth";
import checkoutRouter from "./routes/checkout";

const app = express();

app.use(express.json());
app.use("/api/fanfare", fanfareAuthRouter);
app.use("/api", checkoutRouter);

app.listen(3000);

Frontend (React)

// App.tsx
function App() {
  const { user } = useYourAuth();

  return (
    <FanfareProvider organizationId="org_xxx" publishableKey="pk_live_xxx">
      <FanfareAuthSync user={user} />
      <YourApp />
    </FanfareProvider>
  );
}

function FanfareAuthSync({ user }: { user: User | null }) {
  useFanfareExternalAuth(user);
  return null;
}

Troubleshooting

Exchange Code Expired

Codes expire after 60 seconds
Generate new code immediately before exchange
Check for network latency issues

Secret Key Errors

Verify key has sk_ prefix (not pk_)
Check key permissions in dashboard
Ensure the key belongs to the correct Fanfare organization and account

Token Validation Fails

Verify consumer ID matches
Check token hasn’t expired
Ensure the request comes from the active session

What’s Next

Checkout Integration - Complete checkout flows
Webhooks - Server-side event handling
Error Handling - Robust error management

​JWT Tokens Guide

​Overview

​Prerequisites

​When to Use JWT Authentication

​Authentication Architecture

​Step 1: External Authentication Endpoint

​Node.js/Express

​Python/FastAPI

​Step 2: Client-Side Exchange

​Step 3: Grant Validation Endpoint

​Node.js/Express

​Step 4: Secure Checkout Flow

​Step 5: JWT Token Structure

​Access Token Payload

​Admission Grant Context

​Step 6: Security Best Practices

​Protect Your Secret Key

​Validate Token Origin

​Implement Rate Limiting

​Validate Claims

​Step 7: Error Handling

​Complete Integration Example

​Backend (Node.js)

​Frontend (React)

​Troubleshooting

​Exchange Code Expired

​Secret Key Errors

​Token Validation Fails

​What’s Next

JWT Tokens Guide

Overview

Prerequisites

When to Use JWT Authentication

Authentication Architecture

Step 1: External Authentication Endpoint

Node.js/Express

Python/FastAPI

Step 2: Client-Side Exchange

Step 3: Grant Validation Endpoint

Node.js/Express

Step 4: Secure Checkout Flow

Step 5: JWT Token Structure

Access Token Payload

Admission Grant Context

Step 6: Security Best Practices

Protect Your Secret Key

Validate Token Origin

Implement Rate Limiting

Validate Claims

Step 7: Error Handling

Complete Integration Example

Backend (Node.js)

Frontend (React)

Troubleshooting

Exchange Code Expired

Secret Key Errors

Token Validation Fails

What’s Next