> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fanfare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Best Practices

> Secure authentication patterns for Fanfare integrations.

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:

```typescript theme={null}
// 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:

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

> [!WARNING]
>
> Never expose secret keys in client-side code, mobile apps, or public repositories.

### Secure Key Storage

**Environment Variables**:

```bash theme={null}
# .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:

1. Generate new key in dashboard
2. Update your application
3. Test thoroughly
4. Revoke old key

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// Step 1: Request OTP
await client.auth.requestOTP({
  method: "email",
  email: "user@example.com",
});

// Step 2: Verify OTP
const session = await client.auth.verifyOTP({
  email: "user@example.com",
  code: "123456",
});
```

**OTP Security**:

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

### Session Management

```typescript theme={null}
// 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:

```json theme={null}
{
  "sub": "consumer_id",
  "org": "organization_id",
  "iat": 1705312800,
  "exp": 1705399200,
  "type": "consumer"
}
```

### Token Handling

> [accordion] Don't store tokens in localStorage for sensitive apps
>
> localStorage is vulnerable to XSS attacks. For high-security applications, consider httpOnly cookies.

> [accordion] Don't include tokens in URLs
>
> URLs can be logged, cached, and shared. Use headers for token transmission.

> [accordion] Do handle token expiration
>
> ```typescript theme={null}
> client.on("auth:session-expired", async () => {
>   // Attempt refresh
>   try {
>     await client.auth.refresh();
>   } catch {
>     // Redirect to login
>     redirectToLogin();
>   }
> });
> ```

> [accordion] Do validate tokens server-side
>
> When processing handoff tokens, always validate on your server.
>
> ```typescript theme={null}
> // Server-side validation
> const isValid = await validateHandoffToken(token, secretKey);
> ```

## Server-Side Authentication

### Validating Consumer Requests

When consumers interact with your backend:

```typescript theme={null}
// 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:

```typescript theme={null}
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

> [card] Exposing secret keys
>
> **Wrong**: Including sk\_ keys in client bundles
> **Right**: Only use pk\_ keys client-side

> [card] Not validating handoffs
>
> **Wrong**: Trusting client-sent handoff tokens **Right**: Always validate tokens server-side

> [card] Ignoring token expiration
>
> **Wrong**: Assuming tokens are always valid **Right**: Handle expiration and refresh

> [card] Skipping webhook verification
>
> **Wrong**: Processing webhooks without checking signature
> **Right**: Always verify webhook signatures

## Related Resources

* [Security Overview](https://docs.fanfare.io/resources/security/overview.md) - Security architecture
* [Webhook Debugging](https://docs.fanfare.io/resources/troubleshooting/webhook-debugging.md) - Webhook security
* [API Errors](https://docs.fanfare.io/resources/troubleshooting/api-errors.md) - Auth error handling


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.