QR Code Login API
Enable secure passwordless authentication by scanning QR codes with the mobile app
QR Code Login API
Enable seamless cross-device authentication. Users can log into web or desktop applications by scanning a QR code with their authenticated mobile app.
Mobile-First
Scan QR codes with the OrbVPN mobile app for instant authentication.
Passwordless Security
No password entry required. Authentication happens through your trusted device.
Instant Login
Real-time authentication with sub-second confirmation.
How It Works
Generate QR Code
Your application calls the generateQrCode mutation to create a unique QR code with session information.
Display QR Code
Show the QR code image on screen. The code contains a unique session ID and deep link URL.
User Scans Code
User opens OrbVPN mobile app and scans the QR code. App validates the session and authenticates.
Session Activated
Poll the session status or use WebSocket. Once confirmed, receive the access token.
Endpoint Overview
/graphqlGenerate a QR code for passwordless authentication. Returns the QR code image, session ID, and expiration time.
Generate QR Code
mutation GenerateQRCode {
generateQrCode {
qrCodeImage
sessionId
qrCodeValue
deepLinkUrl
expiresAt
status
}
}HTTP Request:
curl -X POST https://api.orbnet.com/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "mutation GenerateQRCode { generateQrCode { qrCodeImage sessionId qrCodeValue deepLinkUrl expiresAt status } }"
}'Response Fields
{
"data": {
"generateQrCode": {
"qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"sessionId": "qr_sess_abc123def456",
"qrCodeValue": "orbvpn://auth?session=qr_sess_abc123def456",
"deepLinkUrl": "orbvpn://auth?session=qr_sess_abc123def456",
"expiresAt": "2025-01-15T10:35:00Z",
"status": "PENDING"
}
}
}qrCodeImage
Base64-encoded PNG image of the QR code. Display directly in an <img> tag.
sessionId
Unique identifier for this login session. Use to poll for authentication status.
qrCodeValue
The raw value encoded in the QR code. Contains the deep link URL.
deepLinkUrl
URL that opens the OrbVPN app directly when clicked on mobile devices.
expiresAt
ISO 8601 timestamp when the QR code expires. Generate new code after expiry.
status
Current status: PENDING, SCANNED, CONFIRMED, EXPIRED, or CANCELLED.
Check Session Status
After generating the QR code, poll the session status to detect when the user has authenticated:
query CheckQRSession($sessionId: String!) {
checkQrSession(sessionId: $sessionId) {
status
accessToken
}
}Variables:
{
"sessionId": "qr_sess_abc123def456"
}{
"data": {
"checkQrSession": {
"status": "PENDING",
"accessToken": null
}
}
}{
"data": {
"checkQrSession": {
"status": "SCANNED",
"accessToken": null
}
}
}{
"data": {
"checkQrSession": {
"status": "CONFIRMED",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
}{
"data": {
"checkQrSession": {
"status": "EXPIRED",
"accessToken": null
}
}
}Session Status Flow
PENDING
QR code generated, waiting for user to scan. Continue polling.
SCANNED
User scanned the code. Waiting for them to confirm in the app.
CONFIRMED
Authentication successful! Access token is available.
EXPIRED
QR code expired (5 minutes). Generate a new one.
Implementation Best Practices
Show Loading State
When status is SCANNED, show 'Confirming...' to indicate the user is in the approval step.
Auto-Refresh QR
When status becomes EXPIRED, automatically generate a new QR code without user action.
Poll Efficiently
Poll every 2-3 seconds. Use WebSocket if available for real-time updates.
Show Expiry Timer
Display countdown to QR expiration. Helps users understand urgency to scan.
Fallback Option
Always provide email/password login as fallback if user can't scan QR code.
Mobile Deep Link
On mobile web, show 'Open in App' button using deepLinkUrl instead of QR code.
Error Handling
EXPIRED
QR code expired after 5 minutes. Generate a new code automatically.
CANCELLED
User cancelled the authentication in the mobile app. Offer to try again.
SESSION_NOT_FOUND
Invalid session ID. May have been cleaned up. Generate new QR code.
DEVICE_NOT_TRUSTED
Mobile device not authorized. User needs to verify their mobile app first.
Security Considerations
Security Best Practices
- Never reuse session IDs: Each QR code should have a unique session
- Short expiration: QR codes expire in 5 minutes to prevent capture attacks
- Confirm on device: Users must explicitly confirm login on their mobile device
- One-time use: Once authenticated, the session cannot be reused
Related Endpoints
Enable Passwordless Authentication
Improve security and user experience with QR code login. Users can authenticate on any device by simply scanning with their phone.