Authentication Best Practices

This guide covers secure authentication practices for integrating with Fanfare.

API Key Management

Types of Keys

Key Type	Format	Usage	Exposure
Publishable Key	`pk_test_...` / `pk_live_...`	Client-side SDK	Safe for clients
Secret Key	`sk_test_...` / `sk_live_...`	Server-side API	Never expose

Publishable Keys

Publishable keys are designed for client-side use:

// Client-side: OK
const client = new FanfareClient({
  publishableKey: process.env.NEXT_PUBLIC_FANFARE_KEY,
});

Capabilities:

Initialize SDK
Enter experiences
Check queue status
Consumer authentication

Limitations:

Cannot access admin functions
Cannot read other users’ data
Rate limited more aggressively

Secret Keys

Secret keys provide full API access:

// Server-side ONLY
const response = await fetch("https://admin.fanfare.io/api/experiences", {
  headers: {
    Authorization: `Bearer ${process.env.FANFARE_SECRET_KEY}`,
  },
});

Never expose secret keys in client-side code, mobile apps, or public repositories.

Secure Key Storage

Environment Variables:

# .env (never commit this file)
FANFARE_SECRET_KEY=sk_live_...
FANFARE_PUBLISHABLE_KEY=pk_live_...

Secrets Managers:

AWS Secrets Manager
Google Secret Manager
HashiCorp Vault
Vercel Environment Variables

Key Rotation

Rotate keys periodically or after potential exposure:

Generate new key in dashboard
Update your application
Test thoroughly
Revoke old key

// Handle key rotation gracefully
const client = new FanfareClient({
  publishableKey: process.env.FANFARE_KEY,
  onUnauthorized: () => {
    // Key may have been rotated
    console.error("API key invalid - check for rotation");
  },
});

Consumer Authentication

Authentication Methods

Fanfare supports multiple consumer authentication methods:

Method	Use Case	Security Level
Guest	Anonymous access	Basic
Email OTP	Verified email	Medium
Phone OTP	Verified phone	Medium
SSO	Enterprise	High

Guest Authentication

For anonymous access with device binding:

// Create guest session
const session = await client.auth.guest();

// Guest has limited capabilities
// - Enter experiences
// - Join queues
// - Cannot link to authenticated account later

OTP Authentication

For verified consumer identity:

// Step 1: Request OTP
await client.auth.requestOTP({
  method: "email",
  email: "[email protected]",
});

// Step 2: Verify OTP
const session = await client.auth.verifyOTP({
  email: "[email protected]",
  code: "123456",
});

OTP Security:

Codes expire after 10 minutes
Limited retry attempts
Rate limited requests
Invalid codes logged for monitoring

Session Management

// Get current session
const session = client.auth.getSession();

// Check authentication state
if (session?.isAuthenticated) {
  // User is verified
} else if (session?.isGuest) {
  // Guest session
} else {
  // No session
}

// Refresh session
await client.auth.refresh();

// Logout
await client.auth.logout();

Token Security

JWT Structure

Consumer tokens are JWTs with these claims:

{
  "sub": "consumer_id",
  "org": "organization_id",
  "iat": 1705312800,
  "exp": 1705399200,
  "type": "consumer"
}

Token Handling

Don't store tokens in localStorage for sensitive apps

localStorage is vulnerable to XSS attacks. For high-security applications, consider httpOnly cookies.

Don't include tokens in URLs

URLs can be logged, cached, and shared. Use headers for token transmission.

Do handle token expiration

client.on("auth:session-expired", async () => {
  // Attempt refresh
  try {
    await client.auth.refresh();
  } catch {
    // Redirect to login
    redirectToLogin();
  }
});

Do validate tokens server-side

When processing handoff tokens, always validate on your server.

// Server-side validation
const isValid = await validateHandoffToken(token, secretKey);

Server-Side Authentication

Validating Consumer Requests

When consumers interact with your backend:

// Your API endpoint
app.post("/api/checkout", async (req, res) => {
  const handoffToken = req.body.handoffToken;

  // Validate with Fanfare
  const response = await fetch("https://admin.fanfare.io/api/handoffs/validate", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FANFARE_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ token: handoffToken }),
  });

  if (!response.ok) {
    return res.status(401).json({ error: "Invalid handoff" });
  }

  const handoff = await response.json();
  // Process checkout with validated consumer
});

Webhook Authentication

Verify webhook signatures:

import crypto from "crypto";

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post("/webhooks/fanfare", (req, res) => {
  const signature = req.headers["x-fanfare-signature"];

  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Process webhook
});

Security Checklist

Development

Use test keys only in development
Never commit keys to version control
Add .env to .gitignore
Use separate test and production keys

Production

Use live keys in production
Store keys in secrets manager
Enable key rotation policy
Monitor for unauthorized access
Set up alerts for authentication failures

Code Review

No hardcoded credentials
Secret keys only in server-side code
Token handling follows best practices
Webhook signatures verified
Error messages don’t leak sensitive info

Common Mistakes

Exposing secret keys

Wrong: Including sk_ keys in client bundles Right: Only use pk_ keys client-side

Not validating handoffs

Wrong: Trusting client-sent handoff tokens Right: Always validate tokens server-side

Ignoring token expiration

Wrong: Assuming tokens are always valid Right: Handle expiration and refresh

Skipping webhook verification

Wrong: Processing webhooks without checking signature Right: Always verify webhook signatures

Security Overview - Security architecture
Webhook Debugging - Webhook security
API Errors - Auth error handling

Overview

Best Practices

Troubleshooting

Security

Support

API Key Management

Types of Keys

Publishable Keys

Secret Keys

Secure Key Storage

Key Rotation

Consumer Authentication

Authentication Methods

Guest Authentication

OTP Authentication

Session Management

Token Security

JWT Structure

Token Handling

Server-Side Authentication

Validating Consumer Requests

Webhook Authentication

Security Checklist

Development

Production

Code Review

Common Mistakes

Exposing secret keys

Not validating handoffs

Ignoring token expiration

Skipping webhook verification

​API Key Management

​Types of Keys

​Publishable Keys

​Secret Keys

​Secure Key Storage

​Key Rotation

​Consumer Authentication

​Authentication Methods

​Guest Authentication

​OTP Authentication

​Session Management

​Token Security

​JWT Structure

​Token Handling

​Server-Side Authentication

​Validating Consumer Requests

​Webhook Authentication

​Security Checklist

​Development

​Production

​Code Review

​Common Mistakes

Exposing secret keys

Not validating handoffs

Ignoring token expiration

Skipping webhook verification

​Related Resources

API Key Management

Types of Keys

Publishable Keys

Secret Keys

Secure Key Storage

Key Rotation

Consumer Authentication

Authentication Methods

Guest Authentication

OTP Authentication

Session Management

Token Security

JWT Structure

Token Handling

Server-Side Authentication

Validating Consumer Requests

Webhook Authentication

Security Checklist

Development

Production

Code Review

Common Mistakes

Related Resources