Skip to main content

​
Authentication

The AxonVault SDK handles user authentication via social login providers. All authentication is managed automatically by the SDK.

​
Initialize SDK

import { AxonVaultEmbedded } from '@axonvault/embedded-wallet-sdk';

const axonVault = new AxonVaultEmbedded({
  projectId: 'proj_abc123',
  environment: 'production' // or 'development'
});

​
Social Login

​
Google Sign-In

import { GoogleLogin } from '@react-oauth/google';

function LoginButton() {
  const handleGoogleLogin = async (credentialResponse) => {
    try {
      const user = await axonVault.authenticate({
        provider: 'google',
        idToken: credentialResponse.credential
      });
      
      console.log('User authenticated:', user);
      // User is now authenticated, SDK manages tokens automatically
    } catch (error) {
      console.error('Authentication failed:', error);
    }
  };
  
  return (
    <GoogleLogin
      onSuccess={handleGoogleLogin}
      onError={() => console.log('Login Failed')}
    />
  );
}

​
Apple Sign-In

import AppleSignin from 'react-apple-signin-auth';

function AppleLoginButton() {
  const handleAppleLogin = async (response) => {
    try {
      const user = await axonVault.authenticate({
        provider: 'apple',
        idToken: response.authorization.id_token
      });
      
      console.log('User authenticated:', user);
    } catch (error) {
      console.error('Authentication failed:', error);
    }
  };
  
  return (
    <AppleSignin
      authOptions={{
        clientId: 'your.client.id',
        scope: 'email name',
        redirectURI: 'https://yourapp.com/callback',
        usePopup: true
      }}
      onSuccess={handleAppleLogin}
    />
  );
}

​
Email Login

// Send magic link
await axonVault.sendMagicLink({
  email: '[email protected]'
});

// Verify magic link (in callback handler)
const user = await axonVault.verifyMagicLink({
  email: '[email protected]',
  token: magicLinkToken
});

​
Get Current User

// Get authenticated user
const user = await axonVault.getCurrentUser();

if (user) {
  console.log('User ID:', user.userId);
  console.log('Email:', user.email);
  console.log('Provider:', user.provider);
} else {
  console.log('User not authenticated');
}

​
Check Authentication Status

// Check if user is authenticated
const isAuthenticated = await axonVault.isAuthenticated();

if (isAuthenticated) {
  // User is logged in
} else {
  // Show login UI
}

​
Sign Out

// Sign out current user
await axonVault.signOut();

// SDK automatically clears tokens and wallet state

​
Token Management

The SDK automatically manages JWT tokens:
  • Automatic Refresh: Tokens are refreshed before expiration
  • Secure Storage: Tokens stored securely (httpOnly cookies in browser)
  • Error Handling: Automatic retry on token expiration
You don’t need to manually manage tokens. The SDK handles everything: 
// SDK automatically refreshes tokens when needed
// No manual token management required

// If you need to manually refresh (rarely needed)
await axonVault.refreshAuth();

​
Event Listeners

Listen for authentication events: 
// User authenticated
axonVault.on('auth:authenticated', (user) => {
  console.log('User authenticated:', user);
  // Load user's wallets
});

// User signed out
axonVault.on('auth:signedOut', () => {
  console.log('User signed out');
  // Clear UI state
});

// Token refreshed
axonVault.on('auth:tokenRefreshed', () => {
  console.log('Token refreshed');
});

​
Error Handling

import { AuthenticationError } from '@axonvault/embedded-wallet-sdk';

try {
  await axonVault.authenticate({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    switch (error.code) {
      case 'INVALID_TOKEN':
        console.error('Invalid ID token');
        break;
      case 'PROVIDER_ERROR':
        console.error('Provider authentication failed');
        break;
      case 'USER_NOT_FOUND':
        console.error('User not found');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
  }
}

​
Best Practices

  • Always use HTTPS in production
  • Validate ID tokens on your backend if needed
  • Don’t store sensitive data in localStorage
  • Use httpOnly cookies for token storage (SDK handles this)
  • Show loading states during authentication
  • Handle errors gracefully with user-friendly messages
  • Provide clear sign-out functionality
  • Remember user’s last authentication method
  • SDK caches authentication state
  • Tokens are refreshed in background
  • Minimal network requests