Authentication Methods Update - December 2025

🎉 What's New

Bridge Payments now supports enhanced authentication methods for both authenticated users and guest users, making integration simpler and more secure.

---

✨ New Features

1. X-Guest-Token Header (NEW)

A dedicated header for guest authentication, providing a cleaner and more secure alternative to query parameters.

Before:

// Query parameter (less secure, visible in URLs)
fetch('/bridge-payment/payments?token=guest_abc123')

After:

// Header-based (more secure, not visible in URLs)
fetch('/bridge-payment/payments', {
  headers: {
    'X-Guest-Token': 'guest_abc123'
  }
})

Benefits:

• ✅ More secure (not logged in browser history)
• ✅ Cleaner URLs
• ✅ Consistent with X-Session-ID pattern
• ✅ Works with all HTTP methods

---

2. Query Parameters for All HTTP Methods (IMPROVED)

Guest token query parameters (?token=) now work with all HTTP methods, not just GET.

Before:

// ❌ Only GET requests worked
fetch('/bridge-payment/payments?token=guest_abc123') // ✅ Works

// ❌ POST/PUT/DELETE didn't work with query parameters
fetch('/bridge-payment/addresses?token=guest_abc123', {
  method: 'POST',
  body: JSON.stringify({ ... })
}) // ❌ Didn't work

After:

// ✅ All HTTP methods now work
fetch('/bridge-payment/payments?token=guest_abc123') // ✅ GET
fetch('/bridge-payment/addresses?token=guest_abc123', {
  method: 'POST',
  body: JSON.stringify({ ... })
}) // ✅ POST
fetch('/bridge-payment/payment-methods/pm_123?token=guest_abc123', {
  method: 'PUT',
  body: JSON.stringify({ ... })
}) // ✅ PUT
fetch('/bridge-payment/payment-methods/pm_123?token=guest_abc123', {
  method: 'DELETE'
}) // ✅ DELETE

---

📋 Complete Authentication Methods

Authenticated Users (Session-Based)

Method	Example	Priority	Security	Recommended
X-Session-ID header	X-Session-ID: abc123	2	⭐⭐⭐	✅ Primary
Authorization: Bearer	Authorization: Bearer abc123	1	⭐⭐⭐	✅ Yes
?session_id= query	?session_id=abc123	4	⭐⭐	⚠️ Fallback

Guest Users (Token-Based)

Method	Example	Priority	Security	Recommended
X-Guest-Token header ✨ NEW	X-Guest-Token: guest_abc123	3	⭐⭐⭐	✅ Primary
Authorization: Token	Authorization: Token guest_abc123	1	⭐⭐⭐	✅ Yes
?token= query ✨ IMPROVED	?token=guest_abc123	5	⭐⭐	⚠️ Fallback

---

🔄 Migration Guide

No Breaking Changes!

All existing authentication methods continue to work. This is a backward-compatible update.

Recommended Updates

For Guest Authentication:

// Before (still works, but less secure)
const response = await fetch(
  `/bridge-payment/payments?token=${guestToken}`
);

// After (recommended - more secure)
const response = await fetch('/bridge-payment/payments', {
  headers: {
    'X-Guest-Token': guestToken
  }
});

For Guest POST/PUT/DELETE Requests:

// Before (didn't work with query parameters)
const response = await fetch('/bridge-payment/addresses', {
  method: 'POST',
  headers: {
    'Authorization': `Token ${guestToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ... })
});

// After (now works with query parameters too!)
const response = await fetch(
  `/bridge-payment/addresses?token=${guestToken}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ... })
  }
);

// Or use the new X-Guest-Token header (recommended)
const response = await fetch('/bridge-payment/addresses', {
  method: 'POST',
  headers: {
    'X-Guest-Token': guestToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ... })
});

---

📚 Updated Documentation

The following documentation pages have been updated:

• ✅ Authentication API - Complete authentication guide
• ✅ Authentication priority order
• ✅ Security considerations
• ✅ Guest checkout flow examples

---

🔒 Security Recommendations

Most Secure (Use These):

1. X-Session-ID header (authenticated users)
2. X-Guest-Token header (guest users) ✨ NEW
3. Authorization: Bearer header (authenticated users)
4. Authorization: Token header (guest users)

Less Secure (Use Only When Necessary): 5. ?session_id= query parameter 6. ?token= query parameter

Why Headers are Better:

• Not logged in browser history
• Not logged in server access logs
• Not cached by proxies
• Not visible in URLs
• Not exposed in referrer headers

---

📖 Learn More

• Guest Checkout Guide - Learn about guest checkout flows
• Organizations Guide - Multi-tenant support
• Subscriptions Guide - Recurring payments
• Testing Guide - Test your integration

---

Questions? Check the guides above for complete examples and use cases.