Authentication API

Bridge Payments supports multiple authentication methods for both authenticated users and guest checkout flows.

Authentication Methods

1. Session-Based Authentication (Authenticated Users)

For users with active sessions in your Flowless backend.

Method A: X-Session-ID Header (Recommended)

bash

curl -X GET "https://your-instance.pubflow.com/bridge-payment/payments" \
  -H "X-Session-ID: 1dc72119bc5eb3a74bfda3d73da59a5f71b1086a" \
  -H "Content-Type: application/json"

JavaScript Example:

javascript

const response = await fetch('/bridge-payment/payments', {
  headers: {
    'X-Session-ID': sessionId,
    'Content-Type': 'application/json'
  }
});

Method B: Authorization Bearer Header

bash

curl -X GET "https://your-instance.pubflow.com/bridge-payment/payments" \
  -H "Authorization: Bearer 1dc72119bc5eb3a74bfda3d73da59a5f71b1086a" \
  -H "Content-Type": application/json"

JavaScript Example:

javascript

const response = await fetch('/bridge-payment/payments', {
  headers: {
    'Authorization': `Bearer ${sessionId}`,
    'Content-Type': 'application/json'
  }
});

Method C: Query Parameter

bash

curl -X GET "https://your-instance.pubflow.com/bridge-payment/payments?session_id=1dc72119bc5eb3a74bfda3d73da59a5f71b1086a"

JavaScript Example:

javascript

const response = await fetch(`/bridge-payment/payments?session_id=${sessionId}`);

When to Use Query Parameters

Query parameters are useful for:

Simple GET requests from browsers
URL-based authentication for webhooks
Testing and debugging scenarios
Applications with limited header control

2. Guest Token Authentication

For guest users who completed a checkout and need to access their data later.

How Guest Tokens Work

Guest Checkout: User completes payment with guest_data (email, name)
Token Generation: Your Flowless backend generates a token linked to the guest's email
Token Usage: Guest uses ?token=xxx to access their payments, payment methods, etc.
Token Validation: Bridge Payments validates the token with Flowless and retrieves the guest's email

Using Guest Tokens (Query Parameter)

Guest tokens are passed as query parameters in the URL:

bash

# List guest's payments
curl -X GET "https://your-instance.pubflow.com/bridge-payment/payments?token=guest_token_abc123"

# List guest's payment methods
curl -X GET "https://your-instance.pubflow.com/bridge-payment/payment-methods?token=guest_token_abc123"

# Get specific payment details
curl -X GET "https://your-instance.pubflow.com/bridge-payment/payments/pay_123?token=guest_token_abc123"

# Get specific payment method details
curl -X GET "https://your-instance.pubflow.com/bridge-payment/payment-methods/pm_123?token=guest_token_abc123"

JavaScript Example:

javascript

// List all payments for this guest
const paymentsResponse = await fetch(
  `/bridge-payment/payments?token=${guestToken}`
);
const payments = await paymentsResponse.json();

// List all saved payment methods for this guest
const methodsResponse = await fetch(
  `/bridge-payment/payment-methods?token=${guestToken}`
);
const paymentMethods = await methodsResponse.json();

// Get specific payment details
const paymentResponse = await fetch(
  `/bridge-payment/payments/${paymentId}?token=${guestToken}`
);
const payment = await paymentResponse.json();

React Native Example:

typescript

// Store token after guest checkout
import AsyncStorage from '@react-native-async-storage/async-storage';

// After successful guest payment
await AsyncStorage.setItem('guest_payment_token', guestToken);

// Later, retrieve guest's data
const token = await AsyncStorage.getItem('guest_payment_token');
const response = await fetch(
  `${BRIDGE_URL}/bridge-payment/payments?token=${token}`
);
const { data } = await response.json();

Guest Token Limitations

Guest tokens are query parameters (?token=xxx), not headers
Guest tokens provide access only to the guest user's own data (filtered by email)
Guest tokens have limited lifespans (configurable, default: 1 hour)
Tokens are validated against your Flowless backend on each request
Some endpoints support tokens via fallback validation (even for PUT/DELETE)

What Can Guests Access with Tokens?

With a valid guest token, users can:

Read Operations (GET):

✅ List their payments (GET /payments?token=xxx)
✅ View payment details (GET /payments/:id?token=xxx)
✅ List their saved payment methods (GET /payment-methods?token=xxx)
✅ View payment method details (GET /payment-methods/:id?token=xxx)

Write Operations (PUT/DELETE with Fallback Validation):

✅ Update payment method details (PUT /payment-methods/:id?token=xxx)
✅ Delete payment methods (DELETE /payment-methods/:id?token=xxx)

Limitations:

❌ Cannot create new payments (use guest_data in request body instead)
❌ Cannot access other users' data (filtered by guest email)
❌ Cannot perform admin operations

Token Validation Flow

When a guest token is provided:

Primary Validation: Bridge Payments calls Flowless /auth/token/validate?token=xxx
Extract Email: Gets the guest's email from the validation response
Filter Data: Returns only data where guest_email matches the token's email
Fallback Validation: For PUT/DELETE, if primary validation fails, tries to find email by token in payment history

javascript

// Example: Flowless token validation response
{
  "success": true,
  "user": {
    "id": "guest_user_123",
    "email": "[email protected]",  // ← This email is used to filter data
    "name": "Guest User",
    "userType": "guest",
    "isVerified": true
  },
  "tokenType": "token_login",
  "token_id": "tok_abc123",
  "expires_at": "2025-06-05T03:34:29.000Z"
}

3. Guest Data (No Authentication Required)

For creating payments without any authentication (guest checkout).

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -d '{
    "total_cents": 2000,
    "currency": "USD",
    "provider_id": "stripe",
    "guest_data": {
      "email": "[email protected]",
      "name": "Guest User",
      "phone": "+1234567890"
    }
  }'

JavaScript Example:

javascript

const response = await fetch('/bridge-payment/payments/intents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    total_cents: 2000,
    currency: 'USD',
    provider_id: 'stripe',
    guest_data: {
      email: '[email protected]',
      name: 'Guest User'
    }
  })
});

Authentication Priority Order

When multiple authentication methods are provided, the system checks them in this order:

Authorization Header (Bearer or Token)
X-Session-ID Header
session_id Query Parameter
token Query Parameter (for guest access, GET only)

TIP

Only the first valid authentication method found will be used.

Session Validation

Validate Session

Bridge Payments validates sessions against your Flowless backend:

Validation Endpoint (Flowless):

http

POST /auth/bridge/validate
Content-Type: application/json

{
  "sessionId": "1dc72119bc5eb3a74bfda3d73da59a5f71b1086a"
}

Response:

json

{
  "success": true,
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "name": "John Doe",
    "userType": "user",
    "firstName": "John",
    "lastName": "Doe",
    "isVerified": true
  },
  "session": {
    "id": "1dc72119bc5eb3a74bfda3d73da59a5f71b1086a",
    "userId": "user_123",
    "expiresAt": "2025-07-07T02:55:17.864Z"
  }
}

Validate Guest Token

Validation Endpoint (Flowless):

http

GET /auth/token/validate?token=guest_token_abc123

Response:

json

{
  "success": true,
  "user": {
    "id": "guest_user_123",
    "email": "[email protected]",
    "name": "Guest User",
    "userType": "guest",
    "isVerified": true
  },
  "tokenType": "token_login",
  "token_id": "tok_abc123",
  "expires_at": "2025-06-05T03:34:29.000Z"
}

Complete Guest Checkout Flow with Tokens

Here's the complete flow for guest checkout with token-based access:

Step 1: Guest Creates Payment (No Auth Required)

javascript

// Guest completes checkout without authentication
const response = await fetch('/bridge-payment/payments/intents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
    // No authentication needed!
  },
  body: JSON.stringify({
    total_cents: 5000,
    currency: 'USD',
    concept: 'Product Purchase',
    provider_id: 'stripe',
    guest_data: {
      email: '[email protected]',  // ← Guest's email
      name: 'John Doe'
    }
  })
});

const { data } = await response.json();
// Payment created with guest_email = '[email protected]'

Step 2: Your Backend Generates Guest Token

After successful payment, your Flowless backend generates a token:

javascript

// Your backend (Flowless)
import { generateGuestToken } from './auth';

// Generate token linked to guest email
const guestToken = await generateGuestToken({
  email: '[email protected]',
  name: 'John Doe',
  expiresIn: 3600 // 1 hour
});

// Return token to frontend
return {
  success: true,
  token: guestToken,  // ← Send this to the guest
  message: 'Payment successful! Use this token to view your order.'
};

Step 3: Guest Uses Token to Access Their Data

javascript

// Guest can now view their payments
const paymentsResponse = await fetch(
  `/bridge-payment/payments?token=${guestToken}`
);
const { data: payments } = await paymentsResponse.json();
// Returns only payments where guest_email = '[email protected]'

// Guest can view their saved payment methods
const methodsResponse = await fetch(
  `/bridge-payment/payment-methods?token=${guestToken}`
);
const { data: paymentMethods } = await methodsResponse.json();
// Returns only payment methods where guest_email = '[email protected]'

// Guest can update their payment method
const updateResponse = await fetch(
  `/bridge-payment/payment-methods/${methodId}?token=${guestToken}`,
  {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      alias: 'My Visa Card',
      is_default: true
    })
  }
);

Step 4: Store Token for Later Use

javascript

// React Native - Store token in AsyncStorage
import AsyncStorage from '@react-native-async-storage/async-storage';

await AsyncStorage.setItem('guest_payment_token', guestToken);

// Later, retrieve and use
const token = await AsyncStorage.getItem('guest_payment_token');
const response = await fetch(`/bridge-payment/payments?token=${token}`);

javascript

// Web - Store token in localStorage
localStorage.setItem('guest_payment_token', guestToken);

// Later, retrieve and use
const token = localStorage.getItem('guest_payment_token');
const response = await fetch(`/bridge-payment/payments?token=${token}`);

Security Considerations

Session-Based Authentication

✅ Use X-Session-ID header for best security
✅ Sessions are validated on every request
✅ Sessions can be revoked server-side
✅ Supports full user context (user_id, organization_id, etc.)

Guest Token Authentication

⚠️ Tokens are temporary (default: 1 hour)
⚠️ Tokens are tied to a specific email address
⚠️ Tokens cannot be revoked (until expiration)
⚠️ Tokens provide read-only access to guest's own data
✅ Tokens are validated against Flowless on each request
✅ Tokens are filtered by guest_email for security

Guest Data (No Authentication)

⚠️ Only for creating new payments
⚠️ No access to existing data
⚠️ Cannot list or view previous payments
✅ Simplest checkout flow
✅ No account required

Next Steps

Payments API - Create and manage payments
Payment Methods API - Manage saved payment methods
Guest Checkout Guide - Complete guest checkout implementation
Configuration - Configure Flowless integration

Authentication API ​

Authentication Methods ​

1. Session-Based Authentication (Authenticated Users) ​

Method A: X-Session-ID Header (Recommended) ​

Method B: Authorization Bearer Header ​

Method C: Query Parameter ​

2. Guest Token Authentication ​

How Guest Tokens Work ​

Using Guest Tokens (Query Parameter) ​

Token Validation Flow ​

3. Guest Data (No Authentication Required) ​

Authentication Priority Order ​

Session Validation ​

Validate Session ​

Validate Guest Token ​

Complete Guest Checkout Flow with Tokens ​

Step 1: Guest Creates Payment (No Auth Required) ​

Step 2: Your Backend Generates Guest Token ​

Step 3: Guest Uses Token to Access Their Data ​

Step 4: Store Token for Later Use ​

Security Considerations ​

Session-Based Authentication ​

Guest Token Authentication ​

Guest Data (No Authentication) ​

Next Steps ​

Authentication API

Authentication Methods

1. Session-Based Authentication (Authenticated Users)

Method A: X-Session-ID Header (Recommended)

Method B: Authorization Bearer Header

Method C: Query Parameter

2. Guest Token Authentication

How Guest Tokens Work

Using Guest Tokens (Query Parameter)

Token Validation Flow

3. Guest Data (No Authentication Required)

Authentication Priority Order

Session Validation

Validate Session

Validate Guest Token

Complete Guest Checkout Flow with Tokens

Step 1: Guest Creates Payment (No Auth Required)

Step 2: Your Backend Generates Guest Token

Step 3: Guest Uses Token to Access Their Data

Step 4: Store Token for Later Use

Security Considerations

Session-Based Authentication

Guest Token Authentication

Guest Data (No Authentication)

Next Steps