Integration Patterns - UIP Documentation

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

User Database Schema

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

Authentication Flow States

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

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

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

Request UIP Verification

Call the Identify API to request biometric authentication:API Call:

Include intent describing the verification
Request minimal fields (only need verification confirmation)

Response:

session_id, qr_code (base64 PNG), expires_at

Display UIP Prompt

Show appropriate UI based on device type:Mobile Flow:

Display “Open UIP App” button linking to https://www.uip.id/{session_id}
Show loading state: “Waiting for biometric verification…”

Desktop Flow:

Display QR code prominently (from qr_code in API response)
Show instructions: “Scan with UIP app to complete login”
Add loading indicator

Poll for Completion

Poll GET /v1/identify/:id every 2-3 seconds until status is completed.On Success:

Extract uip_id and audit_id from the response
Grant user access to application
Update frontend to show logged-in state

On Failure/Expired:

Show error message
Allow user to retry UIP verification

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:

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”

Initiate UIP Setup

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

User Completes UIP Setup

User opens UIP app and completes one-time verification:

Scans government ID
Takes biometric selfie
Confirms identity

Link UIP to Account

When polling returns completed:

Extract uip_id from the completed response
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

Support Scenarios You'll Face

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

Phishing Protection

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.

Account Takeover Prevention

Credential stuffing and brute force attacks are ineffective because the second factor (biometric) cannot be remotely compromised.

Audit Trail

Every UIP authentication includes government-verified identity, precise timestamp, and device information — creating a complete audit trail.

Compliance Ready

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

Standard Login

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

Trigger Point

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

Request Step-Up

Call the Identify API to request biometric verification. Show the QR code or deep link button depending on device.

Poll and Verify

Poll GET /v1/identify/:id until completed. 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

Reduced Friction

Users don’t face biometric verification on every login — only when necessary for high-risk operations.

Risk-Based Security

Apply appropriate security based on the sensitivity of the action, not a one-size-fits-all approach.

Regulatory Compliance

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. Poll GET /v1/identify/:id until completed.

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: Professional User Behavior

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: Different Reality

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)

Primary: UIP First

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

Fallback Available

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

Recovery Key Education

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

IT Support Integration

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

Benefits (B2B/Enterprise)

Maximum Security

Professional users get strongest authentication by default, with IT support available for edge cases.

Better User Experience

B2B users who use UIP daily benefit from fastest authentication — no passwords to remember or type.

Reduced IT Costs

Fewer password reset tickets for users who adopt UIP, as biometric is harder to “forget.”

Pattern 5: Platform Delegation

Use Case: Build a platform that makes UIP API calls on behalf of multiple businesses. Instead of each business integrating UIP directly, your platform handles the integration once and serves all customers.

When to Use This Pattern

SaaS platforms serving multiple businesses

Payroll, HR, or compliance platforms needing signatures from employees

Marketplace platforms managing identity verification for sellers

White-label solutions where clients don’t integrate UIP directly

How It Works

Request Authorization

Call POST /v1/authorize with your platform’s client credentials and the scopes you need (e.g., identify:create, sign:create).

Business Approves

Display the QR code to the business owner. They scan it, review the requested permissions, and approve with biometric verification.

Poll for Token

Poll POST /v1/authorize/:id/status with client credentials until completed. You receive a delegation token (uip_at_ prefix) in the response.

Make API Calls on Behalf of Business

Use the delegation token as a Bearer token to make API calls. Billing goes to the business, not the platform.

curl -X POST https://api.uip.digital/v1/identify \
  -H "Authorization: Bearer uip_at_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{"intent": "Verify employee", "requested_data": ["first_name", "last_name"]}'

See the Platform Delegation Guide for full details on scopes, token management, and security best practices.

Choosing the Right Pattern

By Application Type

B2C Applications
B2B / Enterprise

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 Context	Recommended Pattern	Why
B2C app with subscriptions	Pattern 1: Hybrid	Users need guaranteed access to cancel/manage
B2C app with sensitive actions	Pattern 2: Step-Up	Security only when necessary, minimal friction
B2B replacing SMS codes	Pattern 3: MFA	Stronger than SMS, same flow, better UX
Enterprise internal tools	Pattern 4: Progressive	IT support + trained users = UIP-first works
Banking/Financial (any)	Pattern 3: MFA	Compliance + audit trail + legal defensibility
Multi-business platform	Pattern 5: Delegation	Single integration serves all customers

Next Steps

Get API Keys

Start integrating UIP today

QR Integration Guide

Learn how to implement device flows

Platform Delegation

Build platforms for multiple businesses

Getting Started

Guides

​Overview

Hybrid Authentication

Step-Up Authentication

Multi-Factor Authentication

Progressive Enhancement

​Pattern 1: Hybrid Authentication

​Why B2C Needs Email/Password as Primary

​When to Use This Pattern

​Architecture Overview

​Implementation Workflow

​UIP Linking Flow

​User Experience Considerations

Keep UIP Optional

Clear Recovery Path

Subscription Management

Transparent About Keys

​Critical: Account Recovery Reality

​Security Benefits

​Pattern 2: Step-Up Authentication

​When to Use This Pattern

​How It Works

​Example Trigger Points

Financial

Account Changes

Data Access

​Benefits

​Pattern 3: Multi-Factor Authentication (MFA)

​When to Use This Pattern

​How UIP Improves Traditional MFA

Stronger Than SMS

Better Than TOTP Apps

Government Verification

Audit Trail Included

​Implementation

​Pattern 4: Progressive Enhancement

​When to Use This Pattern

​Why This Works for B2B, Not B2C

​User Flow (B2B Context)

​Benefits (B2B/Enterprise)

​Pattern 5: Platform Delegation

​When to Use This Pattern

​How It Works

​Choosing the Right Pattern

​By Application Type

Pattern 1: Hybrid Auth

Pattern 2: Step-Up Auth

Pattern 3: Multi-Factor

Pattern 4: Progressive

​Quick Decision Matrix

​Next Steps

Get API Keys

QR Integration Guide

Platform Delegation

Overview

Pattern 1: Hybrid Authentication

Why B2C Needs Email/Password as Primary

When to Use This Pattern

Architecture Overview

Implementation Workflow

UIP Linking Flow

User Experience Considerations

Critical: Account Recovery Reality

Security Benefits

Pattern 2: Step-Up Authentication

When to Use This Pattern

How It Works

Example Trigger Points

Benefits

Pattern 3: Multi-Factor Authentication (MFA)

When to Use This Pattern

How UIP Improves Traditional MFA

Implementation

Pattern 4: Progressive Enhancement

When to Use This Pattern

Why This Works for B2B, Not B2C

User Flow (B2B Context)

Benefits (B2B/Enterprise)

Pattern 5: Platform Delegation

When to Use This Pattern

How It Works

Choosing the Right Pattern

By Application Type

Quick Decision Matrix

Next Steps