Skip to main content

​
How UIP Authentication Works

UIP’s authentication flow adapts to the user’s device context. The key is asking users upfront whether they want to authenticate on their current device or another device, eliminating guesswork and ensuring the best user experience.

Mobile Flow

User is on mobile and wants to authenticate on this device → UIP opens the mobile app directly, no QR code needed.

Desktop Flow

User is on desktop or wants to use another device → UIP generates a QR code to scan with their mobile UIP app.

​
Best Practice: Always Ask First

Before making any API calls, present users with a choice: “Authenticate on this device” or “Authenticate with another device”. This prevents failed attempts and ensures the optimal flow every time.

Why This Matters

Eliminates device detection errors and edge cases
Respects user preference (they might want to use a different device)
Provides clear user intent for your API integration
Reduces friction and improves conversion rates

​
Implementation Flow

1

Present Device Choice

Show users two clear options before initiating authentication:Option 1: Authenticate on This Device Option 2: Scan QR Code with Another Device
2

Make API Request

Call the Identify API or Sign API with the appropriate parameters based on user choice.For mobile/same device flow, include device_type: "mobile" and your redirect URL. For desktop/QR code flow, include device_type: "desktop".Both flows require your webhook_url for receiving authentication results.
3

Handle API Response

UIP returns different response formats based on the device type:Mobile Response:
  • Type: redirect
  • App URL for opening UIP directly
  • Session ID for tracking
Desktop Response:
  • Type: qr_code
  • QR image data (base64-encoded PNG)
  • Session ID for tracking
4

Display Appropriate UI

For Mobile: Display a button that opens the UIP app using the provided app URL. Show “Opening UIP app…” feedback.For Desktop: Display the QR code image prominently with clear instructions: “Scan with UIP app”
5

Receive Webhook Confirmation

All communication after the initial API call is handled through webhooks. UIP will send authentication results to your webhook URL.The webhook payload includes event type, session ID, status, user data, and timestamp.

​
Webhook Handling

After the user completes authentication in their UIP app, all communication happens through webhooks. This ensures real-time updates regardless of the user’s device or network conditions.
Webhook Security: Your webhook secret is a UUID v4 identifier (without any prefix). Always verify the X-UIP-Signature header using HMAC SHA-256 before processing webhook data.

​
Webhook Events

Your webhook endpoint will receive POST requests with the following event types:
Event: authentication_completedSent when a user successfully authenticates with their biometric.Payload includes:
  • Session ID
  • Status: success
  • User data (based on requested fields)
  • Timestamp

​
Real-time Frontend Updates

Use WebSockets, Server-Sent Events, or short polling to update your frontend when the webhook receives the authentication result. This provides instant feedback to users.

WebSockets

Best for real-time bidirectional communication. Ideal for dashboards and interactive applications.

Server-Sent Events

Simple one-way updates from server to client. Perfect for status updates and notifications.

Short Polling

Fallback option that works everywhere. Check status endpoint every 2-5 seconds until complete.

​
QR Code Display Best Practices

  • Minimum size: 200x200 pixels for reliable scanning
  • Recommended: 256x256 to 300x300 pixels
  • Center the QR code prominently on the page
  • Add adequate white space (quiet zone) around the QR code
  • Show loading indicator while waiting for scan
  • Display clear instructions: “Scan with UIP app”
  • Add animated elements to draw attention to the QR code
  • Show status updates: “QR code scanned, waiting for confirmation”
  • Handle expired QR codes gracefully (typically 5 minutes)
  • Show “Try Again” button to generate new QR code
  • Display clear error messages for connection issues
  • Provide fallback options if QR scanning fails
  • Provide alt text for screen readers
  • Include text instructions alongside QR code
  • Ensure sufficient color contrast for visibility
  • Consider alternative authentication methods for accessibility

​
Session Management

Session Expiration

QR codes expire after 5 minutes. Always check expiration status and generate new codes as needed.

One-Time Use

Each QR code is single-use. After scanning, the session cannot be reused for security.

HTTPS Required

All UIP integrations must use HTTPS in production to prevent man-in-the-middle attacks.

Concurrent Sessions

Support multiple concurrent sessions for users authenticating from different tabs or devices.

​
Testing QR Flows

During development, you can test the QR flow:
1

Use Your $5 Signup Credit

New accounts receive $5 in credits—enough for testing your integration
2

Create Your UIP Identity

Create your own UIP identity to test the full authentication flow end-to-end
3

Verify Webhooks

Use the Test Webhook endpoint to verify your webhook handler is working correctly
4

Test Error Scenarios

Test QR code expiration, user cancellations, and network errors to ensure proper error handling
Testing with real infrastructure: Use your signup credit to test with actual UIP infrastructure. This gives you the full production experience during development.

​
API Reference

Identify API

Full API reference for authentication requests

Sign API

Full API reference for signature requests

Invalidate Session

Cancel active sessions or clean up expired ones

Test Webhook

Test your webhook endpoint before going live

​
Next Steps

Get API Keys

Start integrating UIP in minutes

Identify API Service

Learn about authentication use cases

Error Handling

Handle errors gracefully