Skip to main content

​
Overview

UIP is designed to integrate seamlessly with your existing authentication and signing infrastructure. This guide presents proven integration patterns to help you choose the right approach for your specific use case.

Hybrid Authentication

Add UIP as enhanced security alongside existing email/password systems

Step-Up Authentication

Start with basic auth, require UIP for sensitive operations

Multi-Factor Authentication

Use UIP as a second factor for high-security scenarios

Progressive Enhancement

Offer UIP as the primary option with traditional fallback

​
Pattern 1: Hybrid Authentication

Use Case: You have a B2C application and want to add UIP as enhanced security while keeping email/password as the primary authentication and recovery method.

​
Why B2C Needs Email/Password as Primary

Critical for B2C: UIP recovery requires users to save two unique recovery keys. B2C users are notoriously unreliable with credential management—they lose keys, forget to save them, or don’t understand their importance.Real-world scenarios where users need email/password:
  • Lost phone or device replacement
  • Forgot to save UIP recovery keys
  • Need to cancel or update subscriptions without UIP access
  • Device stolen or damaged
  • Family member needs to manage account in emergency
  • User deleted UIP app accidentally
Without email/password fallback, you’ll face:
  • Massive support overhead dealing with locked-out users
  • Subscription cancellation issues (legal requirement to allow this)
  • User frustration and churn
  • Inability to recover accounts for legitimate users
For B2C, email/password must remain the primary authentication method, with UIP as an optional security enhancement.

​
When to Use This Pattern

B2C applications with subscription management
Users need guaranteed account recovery options
Want to offer enhanced security without forcing adoption
Need to support users who lose devices or credentials
Regulatory or compliance requirements for multi-factor security

​
Architecture Overview

Your user records store both traditional and UIP credentials:User Record:
  • user_id - Primary key
  • email - Email address
  • password_hash - Hashed password (existing)
  • uip_id - UIP identity reference (new, nullable)
  • uip_enabled - Boolean flag for UIP status
  • created_at - Account creation timestamp
  • uip_linked_at - When UIP was linked
State 1: Legacy User (email/password only)
  • User logs in with email and password
  • After successful login, show prompt to link UIP
  • User remains functional without UIP
State 2: Hybrid User (email/password + UIP linked)
  • User logs in with email and password first
  • System requires UIP biometric verification as second step
  • Both factors must succeed for access
State 3: UIP-Primary User (optional evolution)
  • User chooses to use UIP as primary authentication
  • Email/password retained as recovery method
  • Faster login experience with biometric-first flow

​
Implementation Workflow

1

Initial Login (Email/Password)

User enters email and password as usual. Your system validates credentials against existing database.Success: Proceed to Step 2 Failure: Show error and allow retry
2

Check UIP Status

After password verification, check if user has linked UIP:If uip_enabled = false:
  • Grant access immediately
  • Show optional prompt: “Enable UIP for enhanced security”
  • Link to UIP setup flow
If uip_enabled = true:
  • Do NOT grant access yet
  • Proceed to Step 3 for biometric verification
3

Request UIP Verification

Call the Identify API to request biometric authentication:API Call:
  • Include user’s uip_id in request
  • Specify device type (mobile or desktop)
  • Provide webhook URL for receiving result
  • Request minimal fields (only need verification confirmation)
Response:
  • Mobile: App redirect URL
  • Desktop: QR code for scanning
4

Display UIP Prompt

Show appropriate UI based on device type:Mobile Flow:
  • Display “Open UIP App” button
  • Show loading state: “Waiting for biometric verification…”
Desktop Flow:
  • Display QR code prominently
  • Show instructions: “Scan with UIP app to complete login”
  • Add loading indicator
5

Receive Webhook Confirmation

UIP sends authentication result to your webhook endpoint.On Success:
  • Verify webhook signature
  • Extract session_id and status
  • Grant user access to application
  • Update frontend to show logged-in state
On Failure/Cancel:
  • Show error message
  • Allow user to retry UIP verification
  • Optionally provide support contact
6

Complete Session

Create authenticated session for user:
  • Issue session token/cookie
  • Log successful authentication (with both factors)
  • Redirect to user’s intended destination
  • Store audit trail with both authentication methods used

​
UIP Linking Flow

For users who don’t have UIP enabled, provide an opt-in flow:
1

Present UIP Benefits

After user logs in with email/password, show benefits:
  • “Enable biometric login for enhanced security”
  • “No more passwords—use your fingerprint or face”
  • “Same security as government ID verification”
2

Initiate UIP Setup

User clicks “Enable UIP” button. Call the Identify API to start the linking process.Show QR code or app redirect depending on device type.
3

User Completes UIP Setup

User opens UIP app and completes one-time verification:
  • Scans government ID
  • Takes biometric selfie
  • Confirms identity
4

Link UIP to Account

When webhook confirms successful verification:
  • Extract uip_id from webhook payload
  • Update user record: uip_id = <received_id>, uip_enabled = true
  • Show success message: “UIP enabled! Next login will use biometric verification”

​
User Experience Considerations

Keep UIP Optional

NEVER force UIP adoption. B2C users need the freedom to manage their accounts with email/password alone, especially for critical actions like subscription cancellation.

Clear Recovery Path

Always provide obvious “Use email/password instead” options. When users lose UIP access, they need immediate recovery without contacting support.

Subscription Management

Ensure users can cancel subscriptions, update payment methods, and manage billing with email/password alone. Legal requirements in many jurisdictions mandate easy cancellation.

Transparent About Keys

If promoting UIP, be honest about recovery key requirements. Many B2C users will ignore this step, so email/password fallback is essential.

​
Critical: Account Recovery Reality

UIP Recovery Keys: B2C Challenge

UIP uses two recovery keys for account restoration. In B2C contexts:What will happen:
  • 60-80% of users won’t save their recovery keys properly
  • Users will screenshot keys and lose them when upgrading phones
  • Users will save keys in Notes app that doesn’t sync
  • Users won’t understand the importance until it’s too late
Why email/password is mandatory:
  • Immediate account access without recovery key hunt
  • Subscription cancellation always possible (legal requirement)
  • Reduces support tickets by 90%+
  • User can disable lost UIP and re-enable on new device
Real support tickets you’ll receive if UIP is the only option:
  • “I got a new phone and can’t log in to cancel my subscription”
  • “I deleted the UIP app by accident, now I’m locked out”
  • “My phone was stolen and I need to update my credit card”
  • “I never saved those keys you mentioned, can you help?”
  • “My mom needs to manage my account but I’m in the hospital”
With email/password fallback, these become non-issues.

​
Security Benefits

Even if an attacker steals the user’s email and password, they cannot complete authentication without the user’s biometric verification on their registered device.
Credential stuffing and brute force attacks are ineffective because the second factor (biometric) cannot be remotely compromised.
Every UIP authentication includes government-verified identity, precise timestamp, and device information—creating a complete audit trail.
Meets requirements for multi-factor authentication in regulated industries like finance, healthcare, and government services.

​
Pattern 2: Step-Up Authentication

Use Case: Allow basic login with email/password for low-risk operations, but require UIP verification when users attempt sensitive actions like large transfers, account changes, or data exports.

​
When to Use This Pattern

Balance security with user convenience
Different risk levels for different operations
Compliance requirements for high-value transactions
Reduce friction for routine, low-risk activities

​
How It Works

1

Standard Login

User logs in with email/password for basic account access. Grant access to low-risk features immediately.
2

Trigger Point

When user attempts sensitive operation (wire transfer, account settings change, data export), intercept the action.
3

Request Step-Up

Call the Identify API to request biometric verification before allowing the sensitive action.
4

Verify and Proceed

Only after successful UIP verification, allow the sensitive operation to complete. Log both the action and the verification for audit purposes.

​
Example Trigger Points

Financial

Wire transfers, cryptocurrency withdrawals, large purchases, payment method changes

Account Changes

Email change, password reset, phone number update, security settings modification

Data Access

Export personal data, download records, delete account, access sensitive documents

​
Benefits

Users don’t face biometric verification on every login—only when necessary for high-risk operations.
Apply appropriate security based on the sensitivity of the action, not a one-size-fits-all approach.
Meet requirements for transaction verification without over-securing low-risk activities.

​
Pattern 3: Multi-Factor Authentication (MFA)

Use Case: Use UIP as the second factor in a traditional multi-factor authentication flow, replacing SMS codes or authenticator apps with government-verified biometric authentication.

​
When to Use This Pattern

High-security applications (banking, healthcare, government)
Replacing SMS-based 2FA with more secure alternative
Need legally defensible proof of user identity
Compliance with regulations requiring strong MFA

​
How UIP Improves Traditional MFA

Stronger Than SMS

SMS codes can be intercepted, phished, or SIM-swapped. UIP biometrics cannot be stolen remotely.

Better Than TOTP Apps

Time-based codes can be phished or stolen if device is compromised. UIP requires live biometric presence.

Government Verification

Unlike generic authenticator apps, UIP provides proof of government-verified identity.

Audit Trail Included

Every authentication includes cryptographic proof, timestamp, and identity verification—no additional logging needed.

​
Implementation

Replace SMS/TOTP verification step with UIP call. User authenticates with username/password, then completes second factor via UIP biometric scan instead of entering a code.

​
Pattern 4: Progressive Enhancement

Use Case: Offer UIP as the primary, recommended authentication method while maintaining traditional email/password as a fallback. Best for B2B, enterprise, or high-security applications—not recommended for general B2C.

​
When to Use This Pattern

B2B applications with professional users
Enterprise internal tools with IT support available
High-security contexts where users understand credential management
Users are incentivized to protect their accounts (financial, professional)
Not recommended for B2C applications where users manage subscriptions, make purchases, or need guaranteed account access. See Pattern 1 (Hybrid Authentication) for B2C best practices.

​
Why This Works for B2B, Not B2C

B2B users typically:
  • Have IT support to help with account recovery
  • Understand importance of backup credentials
  • Work from managed devices with backup systems
  • Face consequences for losing access (can’t do their job)
  • Are trained on security best practices
Result: Higher likelihood they’ll properly save UIP recovery keys
B2C users typically:
  • Have no IT support—only your customer service
  • Don’t save recovery keys or understand their importance
  • Upgrade phones frequently and lose credentials
  • Need to cancel subscriptions on a whim (legal requirement)
  • Expect “forgot password” to solve everything
Result: Email/password must remain primary, UIP is enhancement only

​
User Flow (B2B Context)

1

Primary: UIP First

Default signup and login options prominently feature UIP. Make it the easiest, most visible path.
2

Fallback Available

Provide “Use email/password instead” link for users who need traditional authentication.
3

Recovery Key Education

For B2B users choosing UIP, emphasize saving recovery keys to corporate password manager or secure storage.
4

IT Support Integration

Provide tools for IT administrators to help users recover accounts when UIP access is lost.

​
Benefits (B2B/Enterprise)

Professional users get strongest authentication by default, with IT support available for edge cases.
B2B users who use UIP daily benefit from fastest authentication—no passwords to remember or type.
Fewer password reset tickets for users who adopt UIP, as biometric is harder to “forget.”

​
Choosing the Right Pattern

​
By Application Type

Recommended: Pattern 1 (Hybrid) or Pattern 2 (Step-Up)

Pattern 1: Hybrid Auth

Email/password primary + UIP enhancementUse when:
  • You have subscriptions or purchases
  • Users need guaranteed account access
  • Recovery key management is unreliable
Result: Security boost without support nightmares

Pattern 2: Step-Up Auth

Basic login + UIP for sensitive actionsUse when:
  • Most actions are low-risk
  • Only financial/sensitive operations need extra security
  • Want to balance convenience and protection
Result: Minimal friction, maximum security where it matters
Avoid Pattern 4 (Progressive Enhancement) for B2C. Users will lose access, create support burden, and legal issues with subscription cancellation.

​
Quick Decision Matrix

Your ContextRecommended PatternWhy
B2C app with subscriptionsPattern 1: HybridUsers need guaranteed access to cancel/manage
B2C app with sensitive actionsPattern 2: Step-UpSecurity only when necessary, minimal friction
B2B replacing SMS codesPattern 3: MFAStronger than SMS, same flow, better UX
Enterprise internal toolsPattern 4: ProgressiveIT support + trained users = UIP-first works
Banking/Financial (any)Pattern 3: MFACompliance + audit trail + legal defensibility

​
Next Steps

Get API Keys

Start integrating UIP today

QR Integration Guide

Learn how to implement device flows

Identify API Reference

Full API documentation