Secure PassFlow Pass Distribution: Best Practices

Overview

When you create a pass through PassFlow, you'll receive a unique URL (e.g., redeem.passflow.io/passes/5wUBzX). These URLs act as bearer tokens - meaning possession of the URL grants the ability to add the pass to a wallet, similar to how having a physical ticket grants entry regardless of who originally purchased it.

This is an inherent characteristic of all mobile wallet passes, not just PassFlow. Therefore, secure distribution of these URLs is crucial and this article explains how to handle them securely.

Your Authentication Responsibility

As a developer integrating with DoorFlow, you are responsible for authenticating your Person records before sharing pass URLs with them. PassFlow intentionally doesn't handle passholder authentication since you have direct knowledge of your Person records and their authentication needs.

Example Secure Flow:

1. Person authenticates with your system
2. Your system verifies their identity
3. Call DoorFlow API to generate pass URL
4. Immediately deliver URL through your secure channel
5. Monitor pass status for successful addition

What PassFlow Provides

URL Security

• Random hash URLs to prevent brute force attempts
• Each URL ties to a specific Person record in DoorFlow
• Single-wallet protection (outlined below)
• Clear status pages showing:
  • If pass is already in use
  • If pass has been revoked
  • Available wallet options
  • Next steps for passholder

Single-Wallet Protection

PassFlow implements protection against multiple active passes from a single URL:

• When a pass is added to a wallet (Apple or Google), that pass is tracked and the credential status is updated through the API and as a webhook.
• The same URL cannot be used to add another pass while there is an active pass
• However, if the pass is removed from the wallet:
  • The URL becomes valid again
  • The pass can be added to another wallet
  • This enables legitimate recovery scenarios like:
    • Accidentally deleting a pass
    • Getting a new phone
    • Resetting a wallet

Example:

1. Alice receives pass URL through a secure channel
2. Adds pass to her Apple Wallet
3. URL won't work for additional wallet additions while pass is active
4. If Alice removes the pass from her wallet:
   • The credential status is updated, applications are notified through a webhook and the API credential 'status' changes.
   • The URL becomes valid again
   • Alice can use the URL to add the pass to a wallet again

This protection:

• Prevents having multiple active passes from one URL
• Allows recovery of accidentally removed passes
• Maintains audit trail of pass additions and removals
• Provides flexibility while maintaining security

Pass Status Tracking

Monitor pass lifecycle through the API/webhooks:

• Wallet addition status (Apple/Google)
• Addition timestamps
• Pass status (active/revoked)
• Update history

This enables an application to provide:

• Usage auditing
• Suspicious activity monitoring
• Distribution verification

Pass Revocation

If a URL is compromised before use:

1. Revoke the pass via API. DELETE /api/v3/credentials/:id
2. Generate new pass URL for the Person record
3. Original URL becomes invalid
4. Any existing wallet passes update to show revoked status

Distribution Options

Configure URL delivery method during setup:

• Through DoorFlow UI (most secure)
• Via API integration (custom implementation)
• Email using person.email (basic verification layer)

Best Practices

1. Treat URLs as sensitive credentials
2. Generate only at point of authenticated distribution
3. Never store URLs
4. No batch generation before authentication
5. Use secure delivery channels
6. Implement revocation process
7. Monitor pass status
8. Log all pass-related events

Security Considerations

Your authentication layer determines initial distribution security. Plan for:

• Person record identity verification
• Secure URL delivery channel
• Status monitoring strategy
• Compromise response process
• Audit logging requirements

Security Protections

Built-in security measures:

• URL generation rate limits per account
• Redemption attempt rate limits per IP
• Suspicious activity monitoring
• Brute force protection

Support

If you have specific security requirements or questions, please contact our support team. We can provide guidance on securing your particular implementation or discuss additional security options if needed.