Authentication Overview

PersonQL provides a complete authentication system built for modern applications with security, scalability, and developer experience in mind.

Authentication Methods

Email/Password Authentication

Traditional email and password authentication with secure password hashing (PBKDF2) and validation.

import { useAuth } from '@personql/react';
 
function SignIn() {
  const { signIn } = useAuth();
 
  const handleSignIn = async () => {
    await signIn({
      email: 'user@example.com',
      password: 'securePassword123',
      rememberMe: true,
    });
  };
}

OAuth Providers

Integrate with popular OAuth providers:

import { useAuth } from '@personql/react';
 
function OAuthSignIn() {
  const { signInWithOAuth } = useAuth();
 
  const handleGoogleSignIn = async () => {
    await signInWithOAuth('google', {
      redirectUri: 'https://yourapp.com/auth/callback',
    });
  };
}

Multi-Factor Authentication (MFA)

Add an extra layer of security with MFA via:

import { useAuth } from '@personql/react';
 
function MFASetup() {
  const { sendMFACode, verifyMFACode } = useAuth();
 
  const handleSendCode = async () => {
    await sendMFACode('sms', '+1234567890');
  };
 
  const handleVerifyCode = async (code) => {
    await verifyMFACode(code);
  };
}

Biometric Authentication (Mobile)

Native biometric authentication for React Native apps:

import { useAuth } from '@personql/react-native';
 
function BiometricSignIn() {
  const { signInWithBiometric, biometricAvailable } = useAuth();
 
  if (biometricAvailable) {
    return <button onClick={signInWithBiometric}>Sign In with Face ID</button>;
  }
}

Session Management

Session Types

Anonymous Sessions

Authenticated Sessions

Token Management

PersonQL uses JWT tokens for authentication:

Access Token

Refresh Token

import { useAuth } from '@personql/react';
 
function TokenRefresh() {
  const { refreshToken, isTokenExpired } = useAuth();
 
  useEffect(() => {
    if (isTokenExpired()) {
      refreshToken();
    }
  }, []);
}

Security Features

Device Fingerprinting

Automatically collect device information for security analysis:

Risk Scoring

Real-time risk assessment based on:

Rate Limiting

Built-in protection against brute force attacks:

Security Headers

Automatic security header management:

Authentication Flow

Sign Up Flow

  1. User enters email and password
  2. Password validation (strength requirements)
  3. Email verification (optional)
  4. Account creation
  5. Automatic sign-in
  6. Session token generation
import { SignUpForm } from '@personql/react';
 
<SignUpForm
  onSuccess={() => navigate('/dashboard')}
  requireEmailVerification={true}
  passwordRequirements={{
    minLength: 8,
    requireUppercase: true,
    requireLowercase: true,
    requireNumbers: true,
    requireSpecialChars: true,
  }}
/>;

Sign In Flow

  1. User enters credentials
  2. Server validates credentials
  3. Risk assessment performed
  4. MFA challenge (if enabled)
  5. Session token generation
  6. User redirected to app
import { SignInForm } from '@personql/react';
 
<SignInForm
  onSuccess={() => navigate('/dashboard')}
  onMFARequired={() => navigate('/mfa')}
/>;

Password Reset Flow

  1. User requests password reset
  2. Reset email sent with token
  3. User clicks link (token validation)
  4. New password entered
  5. Password updated
  6. Automatic sign-in
import { ForgotPasswordForm, ResetPasswordForm } from '@personql/react';
 
// Step 1: Request reset
<ForgotPasswordForm onSuccess={() => setEmailSent(true)} />;
 
// Step 2: Reset password
<ResetPasswordForm token={resetToken} onSuccess={() => navigate('/signin')} />;

Best Practices

Password Security

  1. Enforce Strong Passwords

  2. Password Storage

Session Security

  1. Token Storage

  2. Session Timeout

MFA Implementation

  1. Gradual Rollout

  2. Recovery Options

Configuration

Basic Configuration

import { PersonQLProvider } from '@personql/react';
 
<PersonQLProvider
  config={{
    apiUrl: 'https://app.personql.com',
    clientId: 'your-client-id',
    auth: {
      sessionTimeout: 240, // 4 hours
      tokenRefreshInterval: 840, // 14 minutes
      requireEmailVerification: true,
      enableMFA: true,
    },
  }}
>
  <App />
</PersonQLProvider>;

Advanced Security Configuration

<PersonQLProvider
  config={{
    apiUrl: 'https://app.personql.com',
    clientId: 'your-client-id',
    security: {
      deviceFingerprinting: true,
      riskScoring: true,
      rateLimit: {
        requests: 300,
        window: 60000, // 1 minute
      },
      passwordPolicy: {
        minLength: 12,
        requireUppercase: true,
        requireLowercase: true,
        requireNumbers: true,
        requireSpecialChars: true,
        preventCommon: true,
        preventPrevious: 5,
      },
    },
  }}
>
  <App />
</PersonQLProvider>;

Next Steps

Support