rauth_flutter 2.0.24

RAuth v2 Flutter SDK - Cross-platform reverse authentication library for WhatsApp, Reverse SMS, OneID, and Passkey. Supports Android, iOS, and Web with device info auto-detection, HMAC signing, and ap [...]

RAuth Flutter SDK v2

Cross-platform Flutter library for RAuth v2 reverse authentication. Supports WhatsApp, Reverse SMS, OneID, and Passkey authentication methods.

Features

• ✅ Multiple Auth Methods: WhatsApp, Reverse SMS, OneID, Passkey
• ✅ Cross-Platform: Android, iOS, and Web support
• ✅ Auto Device Detection: Automatic device info and IP detection
• ✅ HMAC Signing: Secure mobile authentication
• ✅ Start Verification: Automatically opens verification intents/deeplinks
• ✅ Await Verification: Automatic session verification
• ✅ Passkey Support: WebAuthn passkey registration
• ✅ Approval System: Request approval tokens for sensitive actions

Installation

Add to your pubspec.yaml:

dependencies:
  rauth_flutter: ^2.0.0

Then run:

flutter pub get

Quick Start

1. Initialize RAuth

import 'package:flutter/material.dart';
import 'package:rauth_flutter/rauth_flutter.dart';

// Create a global navigator key for dialogs (optional but recommended)
final navigatorKey = GlobalKey<NavigatorState>();

void main() {
  Rauth.init(RauthConfig(
    appId: 'your-app-id',
    appSecret: 'your-app-secret',
    debug: false, // Optional, enable debug logs
    navigatorKey: navigatorKey, // Optional, for showing dialogs
  ));
  
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navigatorKey, // Use the same key
      // ... rest of your app
    );
  }
}

2. Start Authentication Session

// Start session with WhatsApp
final session = await Rauth.instance.startSession(
  phone: '[phone]',
  loginMethod: LoginMethod.whatsapp,
);

// Get QR code for display
final qrCode = session.qr; // Automatically gets QR from any method

// Display QR code in your UI

3. Start Verification

// Automatically opens the appropriate verification method
// - WhatsApp: Shows dialog if both apps available, otherwise opens directly
// - SMS: Shows in-app SMS composer dialog
// - OneID: Opens deeplink directly
await session.startVerification();

4. Await Verification

try {
  final status = await Rauth.instance.awaitVerification(
    sessionToken: response.sessionToken,
    phone: '[phone]',
  );

  // Session verified!
  print('Verified via: ${status.verifiedVia}');
  
  // Send session token to your backend
  final jwt = await yourBackend.authenticate(
    sessionToken: status.token,
    phone: status.phone,
  );
} on TimeoutError {
  print('Verification timeout');
} on SessionRevokedError {
  print('Session was revoked');
}

Complete Example

Login Flow

import 'package:rauth_flutter/rauth_flutter.dart';

class AuthService {
  Future<void> loginWithWhatsApp(String phone) async {
    try {
      // 1. Initialize session
      final session = await Rauth.instance.startSession(
        phone: phone,
        loginMethod: LoginMethod.whatsapp,
      );

      // 2. Show QR code
      final qrCode = session.qr; // Automatically gets QR from any method
      // Display QR code in UI

      // 3. Start verification (opens WhatsApp/SMS/OneID)
      await session.startVerification();

      // 4. Await verification
      final status = await Rauth.instance.awaitVerification(
        sessionToken: session.sessionToken,
        phone: phone,
      );

      // 4. Send to backend
      // NOTE: If you are doing signup, you can include additional fields
      // like username, dob, gender along with phone and session_token.
      final jwt = await http.post(
        Uri.parse('https://your-api.com/auth/login'),
        body: jsonEncode({
          'session_token': status.token,
          'phone': status.phone,
          // Optional (for signup):
          // 'username': 'john_doe',
          // 'dob': '1995-08-20',
          // 'gender': 'male',
        }),
      );

      // 5. Store JWT and proceed
      await saveJWT(jwt);
    } catch (e) {
      if (e is TimeoutError) {
        print('Verification timeout');
      } else if (e is SessionRevokedError) {
        print('Session revoked');
      } else {
        print('Error: $e');
      }
    }
  }
}

Passkey Registration & Approval Flow

// 1. Register passkey after session is verified
final passkeyResponse = await Rauth.instance.registerPasskey(
  sessionToken: verifiedSessionToken,
  phone: phone,
  credentialId: webAuthnCredentialId,
  publicKey: webAuthnPublicKey,
);

// 2. Request approval token for sensitive action
final approval = await Rauth.instance.requestApprovalToken(
  sessionToken: verifiedSessionToken,
  phone: phone,
  action: ApprovalAction.transfer,
  amount: 1000.50,
  description: 'Transfer to John Doe',
  metadata: {
    'recipient': '[e-mail]',
    'account_number': '1234567890',
  },
);

// 3. Use approval token in your backend request
final transferResponse = await http.post(
  Uri.parse('https://your-api.com/transfer'),
  headers: {
    'Authorization': 'Bearer $jwt',
    'X-Approval-Token': approval.approvalToken,
  },
  body: jsonEncode({
    'amount': 1000.50,
    'recipient': '[e-mail]',
  }),
);

API Reference

Rauth.init()

Initialize RAuth with configuration.

Rauth.init(RauthConfig(
  appId: 'your-app-id',
  appSecret: 'your-app-secret',
  debug: false, // Optional, enable debug logs
  navigatorKey: navigatorKey, // Optional, for showing dialogs
));

Parameters:

• appId: Your RAuth app ID from dashboard
• appSecret: Your RAuth app secret for HMAC signing
• debug: Enable debug logging (default: false)
• navigatorKey: Global navigator key for showing dialogs (optional)

Rauth.instance.startSession()

Start a new authentication session.

Future<SessionInitResponse> startSession({
  required String phone,
  required LoginMethod loginMethod,
  String? ipOverride,
  String? locationOverride,
  String? deviceNameOverride,
  String? browserOverride,
  String? platformOverride,
  String? deviceFingerprintOverride,
})

Parameters:

• phone: Phone number in international format (e.g., "[phone]")
• loginMethod: LoginMethod.whatsapp, LoginMethod.reverseSms, LoginMethod.oneid, or LoginMethod.passkey
• Device info overrides: Optional parameters to override auto-detected device info

Returns: SessionInitResponse with sessionToken and verificationLinks

session.startVerification()

Start verification by opening the appropriate intent/deeplink. This method automatically detects the login method and handles the verification flow.

Future<void> startVerification()

Behavior:

• WhatsApp: Shows dialog if both regular/business deeplinks available, otherwise opens directly
• SMS: Shows in-app SMS composer dialog with token message (phone number from backend)
• OneID: Directly opens deeplink

Note: No phone parameter needed - only uses deeplinks/tokens from session. If navigatorKey is not provided, dialogs won't be shown and fallback behavior will be used.

Rauth.instance.awaitVerification()

Await session verification until verified or timeout.

Future<SessionStatusResponse> awaitVerification({
  required String sessionToken,
  required String phone,
})

Parameters:

• sessionToken: Session token from startSession()
• phone: Phone number used for session

Returns: SessionStatusResponse when verified

Throws:

• TimeoutError: If timeout reached
• SessionRevokedError: If session is revoked
• SessionNotVerifiedError: If session expired

Rauth.instance.checkSessionStatus()

Check session status once.

Future<SessionStatusResponse> checkSessionStatus({
  required String sessionToken,
  required String phone,
})

Rauth.instance.registerPasskey()

Register a passkey for a verified session.

Future<PasskeyRegistrationResponse> registerPasskey({
  required String sessionToken,
  required String phone,
  required String credentialId,
  required String publicKey,
  String? deviceFingerprint,
})

Rauth.instance.requestApprovalToken()

Request approval token for sensitive actions.

Future<ApprovalResponse> requestApprovalToken({
  required String sessionToken,
  required String phone,
  required ApprovalAction action,
  double? amount,
  String? description,
  Map<String, dynamic>? metadata,
})

Approval Actions:

• ApprovalAction.transfer
• ApprovalAction.withdraw
• ApprovalAction.deleteAccount
• ApprovalAction.changePassword
• ApprovalAction.sessionVerification

Device Info Auto-Detection

The SDK automatically detects device information:

• Mobile (Android/iOS):

  • device_name: Device model (e.g., "iPhone 15", "Pixel 7")
  • platform: OS version (e.g., "iOS 17", "Android 14")
  • browser: Empty (not applicable)
  • ip: Auto-fetched public IP

• Web:

  • device_name: null
  • platform: OS name (e.g., "Windows 11", "macOS", "Linux")
  • browser: Browser name + version (e.g., "Chrome 120")
  • ip: Auto-fetched public IP

All fields can be overridden using optional parameters in startSession().

Error Handling

try {
  await Rauth.instance.startSession(...);
} on NetworkError catch (e) {
  // Network/connection issues
} on AuthError catch (e) {
  // Authentication failed (401, 403)
} on ValidationError catch (e) {
  // Invalid input (400, 402)
} on TimeoutError catch (e) {
  // Verification timeout
} on SessionRevokedError catch (e) {
  // Session was revoked
} on RauthException catch (e) {
  // Other RAuth errors
}

Platform Support

• ✅ Android
• ✅ iOS
• ✅ Web (Chrome, Safari, Firefox, Edge)

License

MIT

Support

For issues and questions, visit https://rauth.io or contact [e-mail]